<zing-grid>

zing-grid is the main tag used to create JavaScript data grids and tables. You enable most of the features on this tag, although there are still many features outside of this tag. Some features require just the attribute, while others allow you to pass a value to the attribute.

Image of the DOM relationship for the zing-grid web component tag

Related Web Components

Attributes

A lot of features on the root web component <zing-grid> are enabled just by their presence. Some attributes require values and those are defined under Example Values.

Example Usage

<zing-grid src="https://cdn.zinggrid.com/datasets/user-roles.json"
  caption="Hello ZingGrid"
  pager
  page-size="2">
</zing-grid>

align

String

Description

Align the contents of all column cells (center|left|right)

Default Value

No Default Value

Accepted Values

No Example Values Demo

caption

String

Description

The caption for the grid.

Default Value

""

Accepted Values

  • "My Caption"
Demo

Description

The type of word-break style for body cells. When not set, cell-break style is normal by default. If the width of a column is set, cell-break is word by default. To overwrite cell-break for cells in a specific column, set cell-break for that column.

Default Value

"normal"

Accepted Values

  • "all"
  • "ellipsis"
  • "normal"
  • "word"
Demo

Description

Adds a class to each <zg-cell> in the grid. This attribute can be applied to both <zing-grid> or <zg-column>. If the attribute is applied to both, <zg-column>'s cell-class overwrites <zing-grid>'s cell-class. To set a class conditionally, set cell-class to the name of the function, which takes in the arguments cellData, domContainer, cellObject.

Default Value

""

Accepted Values

  • "userClassName"
  • "functionName"
Demo

Description

Turn on or off cell editing. Automatically turned on when setting editor or editor-controls.

Default Value

false

Accepted Values

  • "disabled"
  • true
  • false
Demo

Description

Turns off keyboard nav cell focus if set to disabled

Default Value

No Default Value

Accepted Values

  • "disabled"
Demo

Description

Sets the execution method of custom 'icon' type tooltips to either activate on hover or click of the icon

Default Value

"hover"

Accepted Values

  • click
  • hover
Demo

Description

Sets the hover delay in milliseconds before displaying the tooltip. If delay is not specified, it is 1000ms on cell tooltips without an icon and 0ms on cell tooltips with an icon.

Default Value

1000

Accepted Values

  • 2000
Demo

Description

Specify the icon to use for the info column types

Default Value

info

Accepted Values

  • 'checkmark'
Demo

Description

Sets the tooltip-position for the cell

Default Value

"top"

Accepted Values

  • top
  • left
  • right
  • bottom
Demo

Description

Gets the name of the user's custom render function, on window, to use the function's return value as the tooltip content.

Default Value

""

Accepted Values

  • "functionName"
Demo

Description

Points to an external template element to be used as the template for the tooltip display.

Default Value

""

Accepted Values

  • "myTemplateId"
Demo

Description

Sets the style to use for the tooltips. Uses the default style by default. Can set to system to match the tooltips used on icons throughout <zing-grid>

Default Value

default

Accepted Values

  • default
  • system
Demo

col-class

String

Description

Adds a class to each <zg-cell> in targeted <zg-column>. To apply a class conditionally, set the value to the name of the function to run on each cell value. The function takes the parameters fieldIndex, domContainer, and colObject, and returns a string which is the class name to apply.

Default Value

""

Accepted Values

  • "userClassName"
  • "functionName"
Demo

Description

Presence of attribute turns on column resizing for all columns.

Default Value

""

Accepted Values

  • N/A
Demo

Description

Sets the maximum width columns can be set to when resizing.

Default Value

n/a

Accepted Values

  • 150
Demo

Description

Sets the minimum width columns can be set to when resizing.

Default Value

n/a

Accepted Values

  • 150
Demo

Description

Presence of attribute displays column resizing for all columns without hover.

Default Value

""

Accepted Values

  • N/A
Demo

Description

Sets the width each of the columns.

Default Value

fit

Accepted Values

  • "fit"
  • "fitheader"
  • "fitcontent"
  • "stretch"
  • "10%"
  • "150px"
  • 150
Demo

columns

Object

Description

Specifies the columns of the grid. More appropriate to use <zg-column> in most cases or set the property programatically.

Default Value

[]

Accepted Values

  • [{"index": "firstName"}, {"index": "lastName"}]
Demo

Description

Presence of attribute turns on the menu to show and hide columns.

Default Value

""

Accepted Values

  • N/A
Demo

compact

Object

Description

Augments internal themes to a compact mode.

Default Value

N/A

Accepted Values

  • N/A
Demo

config

Object

Description

Used to set multiple grid properties at once. This should never be used directly. This is meant for object instantiation.

Default Value

{}

Accepted Values

  • {"search": true,"pager":true,"caption": "Actors/Actresses","pageSize": 5}
Demo

Description

Turns off delete confirmation if set to disable.

Default Value

true

Accepted Values

  • "disabled"
Demo

Description

Presence attribute which enables the default <zing-grid> context menu or set to the id name of a custom <zg-menu>. If set to a custom menu and <zg-menu> has the replace attribute present, then the custom menu will replace the context menu. Otherwise the contents of the custom meny is appended to the end of context menu.

Default Value

""

Accepted Values

  • N/A
  • "myCustomMenu"
Demo

data

Object

Description

Data for the grid presented as an array or object.

Default Value

""

Accepted Values

  • [{"firstName": "John", "lastName": "Doe"}]
Demo

Description

The data to display in each cell where the data value is null or undefined.

Default Value

""

Accepted Values

  • "N/A"
Demo

dir

String

Description

The HTML standard direction to indicate direction of grid's columns and text.

Default Value

"ltr"

Accepted Values

  • "ltr"
  • "rtl"
Demo

Description

Specifies the action of dragging allowed. By default, if draggable is enabled then drag-action is set "both". This property has no meaning if draggable is not enabled.

Default Value

false

Accepted Values

  • "reorder"
  • "hide"
  • "both"
Demo

draggable

Object

Description

Enables column and/or row dragging.

Default Value

"both"

Accepted Values

  • "rows"
  • "columns"
  • "both"
Demo

editor

String

Description

Turns on the grid editor. Enables single cell editing via double click. Sets the editor to inline (default) or modal.

Default Value

false

Accepted Values

  • "modal"
  • true
Demo

Description

Adds columns for the editor controls. If it is added, default is "all".

Default Value

false

Accepted Values

  • "editor"
  • "remover"
  • "creator"
  • "all"
  • true
  • false
Demo

filter

Boolean

Description

Presence enables on filtering for all columns. Can be turned on/off individually via column.

Default Value

""

Accepted Values

  • N/A
Demo

Description

Adds a class to each <zg-cell> in the <zg-foot>. To apply a class conditionally, set the value to the name of the function to run on each cell value. The function takes the parameters fieldIndex, domContainer, and colObject, and returns a string which is the class name to apply.

Default Value

""

Accepted Values

  • "userClassName"
  • "functionName"
Demo

gridlines

String

Description

Set vertical, horizontal or both grid lines to the grid.

Default Value

No Default Value

Accepted Values

  • "both"
  • "horz"
  • "horizontal"
  • "vert"
  • "vertical"
Demo

Description

Adds a class to each <zg-cell> in the <zg-head>. To apply a class conditionally, set the value to the name of the function to run on each cell value. The function takes the parameters fieldIndex, domContainer, and colObject, and returns a string which is the class name to apply.

Default Value

""

Accepted Values

  • "userClassName"
  • "functionName"
Demo

Description

Setting to disabled will turn off formatting on headers. By default, headers will convert from camel case, dash, and kebab case to properly spaced and capitalized. Or set to a function name to customize formatting of headers.

Default Value

""

Accepted Values

  • "disabled"
  • "functionName"
Demo

Description

Sets the execution method of custom 'icon' type tooltips to either activate on hover or click of the icon

Default Value

"hover"

Accepted Values

  • click
  • hover
Demo

Description

Sets the hover delay in milliseconds before displaying the header tooltip

Default Value

0

Accepted Values

  • 2000
Demo

Description

Sets the tooltip icon position for the tooltip icon in the header cells

Default Value

"right"

Accepted Values

  • left
  • right
  • after-text
Demo

Description

Sets the tooltip-position for the header cell

Default Value

"top"

Accepted Values

  • top
  • left
  • right
  • bottom
Demo

Description

Gets the name of the user's custom render function, on window, to use the function's return value as the tooltip content.

Default Value

""

Accepted Values

  • "functionName"
Demo

Description

Points to an external template element to be used as the template for the tooltip display.

Default Value

""

Accepted Values

  • "myTemplateId"
Demo

Description

Sets what part of the header triggers the tooltip. If set to 'icon', an info icon is added to the header

Default Value

text

Accepted Values

  • text
  • icon
Demo

Description

Sets the style to use for the tooltips. Uses the default style by default. Can set to system to match the tooltips used on icons throughout <zing-grid>

Default Value

default

Accepted Values

  • default
  • system
Demo

height

String

Description

Sets the height of the grid. If the height is less than the size of the content, scrolling is added to grid body.

Default Value

inherit

Accepted Values

  • "500px"
  • "500"
  • 500
Demo

icon-set

Boolean

Description

Allows the user to change the grid icon set to an allowed 3rd-party type (ex: Font-Awesome). To use a custom icon set, the icon set must first be registered.

Default Value

undefined

Accepted Values

  • "fa"
  • "fontawesome"
  • "font-awesome"
Demo

lang

String

Description

Sets the language to use for the grid

Default Value

"en"

Accepted Values

  • "en"
Demo

layout

String

Description

Sets the grid layout to be either card or row and adds <zg-layout-controls> to the grid. The default is based on the size of the user's screen, unless layout is set.

Default Value

""

Accepted Values

  • "card"
  • "row"
Demo

Description

When layout is set, by default layout-controls is enabled. To hide, set layout-controls to disabled. Presence of this attribute will enable <zg-layout-controls> even if layout is not set.

Default Value

""

Accepted Values

  • "disabled"
Demo

loading

Boolean

Description

Presence of attribute adds loading state to grid, which triggers <zg-load-mask> to show. This attribute allows styling the height of the grid (via CSS) before the data has loaded in the grid.

Default Value

""

Accepted Values

  • N/A
Demo

Description

Sets the text to display in the <zg-load-mask> on data load.

Default Value

"loading..."

Accepted Values

  • "ZingGrid is Loading"
Demo

loadmask

String

Description

Set loadmask="disabled" to prevent the <zg-load-mask> from showing on data load.

Default Value

""

Accepted Values

  • "disabled"
Demo

no-data

String

Description

Sets the message that appears in the <zg-no-data> element when there are no records.

Default Value

"There are no records to display."

Accepted Values

  • "No Records"
Demo

page-size

Number

Description

Can be set only if pager is set. Sets the number of records or rows to display per page.

Default Value

50

Accepted Values

  • 10
Demo

Description

Can be set only if pager is set. Sets the number of cards to display per page when in card mode.

Default Value

page-size value

Accepted Values

  • 10
Demo

Description

Can be set only if pager is set. Sets the options for page size in zg-optionl-ist.

Default Value

"5,10,50"

Accepted Values

  • "15,20,35"
Demo

Description

Can be set only if pager. Sets the number of rows to display per page when in row mode.

Default Value

page-size value

Accepted Values

  • 10
Demo

pager

String

Description

Adds pagination functionality and controls to the grid.

Default Value

""

Accepted Values

  • N/A
Demo

Description

Determines max number of page buttons to display. Default is 5

Default Value

5

Accepted Values

  • 3
Demo

Description

Determines which type of pagination to use, input or buttons

Default Value

''

Accepted Values

  • "button-text"
  • "button-arrows"
Demo

params

Object

Description

Name/Value pairs of <zg-param> values. More appropriate to use <zg-param> in most cases.

Default Value

{}

Accepted Values

  • {"idKey": "id", "sortByKey": "_sort", "sortBy": "capital"}
Demo

Description

Sets the total record count. Useful for loadByPage when the response packet does not return total count of records.

Default Value

""

Accepted Values

  • 1000
Demo

row-class

String

Description

Adds a class to each <zg-row> element. To apply a class conditionally, set the value to the name of the function to run on each cell value. The function takes the parameters data, rowIndex (1-based), domRow, and rowObject, and returns a string which is the class name to apply.

Default Value

""

Accepted Values

  • "userClassName"
  • "functionName"
Demo

Description

Presence of attribute adds selector type column to the rows as the first column.

Default Value

""

Accepted Values

  • N/A
Demo

search

Boolean

Description

Presence of attribute turns on the search feature and add <zg-search> to the grid. The search button appears in the caption header.

Default Value

""

Accepted Values

  • N/A
Demo

selector

Boolean

Description

Presence of attribute turns on the selector feature on the grid and adds <zg-selector-mask> to the grid.

Default Value

""

Accepted Values

  • N/A
Demo

Description

Indicates that the grid was completely rendered on the server and embedded in the page.

Default Value

""

Accepted Values

  • N/A
Demo

sort

Boolean

Description

Presence of attribute enables sorting on all columns. It is possible to disable specific columns via the columns object or setting sort="disabled" to specified columns.

Default Value

""

Accepted Values

  • N/A
Demo

sort-intl

String

Description

Overrides default behavior for international sorting. Turn off international sorting with sort-intl="disabled"

Default Value

""

Accepted Values

  • "disabled"
Demo

sorter

function

Description

Override the column sorting by passing in method name of sort function instead. Sorter function takes in two values (a, b) and returns 1, -1, or 0 indicating if a > b, a < b, or a = b.

Default Value

""

Accepted Values

  • "functionName"
Demo

source

String

Description

Defines the source of the data in the grid. Adds the <zg-source> element.

Default Value

""

Accepted Values

  • "Source: Wikipedia"
Demo

src

String

Description

Specifies the absolute or relative URL to fetch data from to populate the grid.

Default Value

""

Accepted Values

  • "https://url-to-your-api"
Demo

static-menu

Boolean

Description

Presence of attribute adds a display button that launch the contextmenu.

Default Value

""

Accepted Values

  • N/A
Demo

Description

Changes the duration a status message will remain visible until it automatically closes (in milliseconds).

Default Value

"3000"

Accepted Values

  • N/A
Demo

Description

Prevent status messages from automatically closing after a delay.

Default Value

""

Accepted Values

  • N/A
Demo

Description

Position the status message in one of nine positions relative to the grid.

Default Value

"top right"

Accepted Values

  • N/A
Demo

Description

Define the regex expression for closing data binding.

Default Value

"]]"

Accepted Values

  • "}}"
Demo

Description

Define the regex expression for starting data binding.

Default Value

"[["

Accepted Values

  • "{{"
Demo

theme

String

Description

Sets the theme of the grid. Built-in themes are specified by keyword, but custom theme names are also accepted by setting a URL path to your custom css theme file. For custom themes, on load set theme to the path to the custom theme file. After, set to theme name to switch themes.

Default Value

"default"

Accepted Values

  • "android"
  • "black"
  • "default"
  • "dark"
  • "ios"
  • "urlToThemeFile"
  • "customThemeName"
Demo

viewport

String

Description

Internal attribute. Should not be set.

Default Value

""

Accepted Values

  • N/A
Demo

Description

Presence of attribute keeps current value of viewport and freezes the breakpoint.

Default Value

""

Accepted Values

  • N/A
Demo

Description

Presence of attribute removes viewport attribute, disabling viewport resizing.

Default Value

""

Accepted Values

  • N/A
Demo

Description

Sets custom viewport breakpoints (value string-object must be valid JSON). NOTE: If you don't set mobile, the grid won't auto-set card or row mode.

Default Value

false

Accepted Values

  • { mobile: 500, test: 600, desktop: 800 }
Demo

width

String

Description

Sets the width of the grid. If the width is less than the size of the content, scroll is added to <zg-body>.

Default Value

inherit

Accepted Values

  • "500"
  • "500px"
  • "5em"
  • "5%"
  • "50vw"
  • 500
Demo

zebra

String

Description

Presence of attribute adds the classes, zebra-1 and zebra-2, alternating on <zg-row> elements. Setting to a list of class names will assign classes in sequential order. For conditional zebra classes, zebra also accepts name of function that returns a class name to use for zebra striping.

Default Value

""

Accepted Values

  • "userCustomStyle"
Demo

CSS Variables

<zing-grid> can be styled with CSS variables, like so:

root: {
  --zing-grid-color: red;
}

Below is a list of all the associated --zing-grid CSS variables. Check out the full list of CSS variables or our Styling Basics guide to learn more about styling the grid.

ZingGrid CSS Variables and Default Values
NameDefaultDescriptionDemoCSS Ref
--zing-grid-background#fffStyles the background of grid
--zing-grid-body-border0Styles the border of grid body
--zing-grid-body-border-bottomvar(--zing-grid-body-border, 0)Styles the bottom border of grid body
--zing-grid-body-border-leftvar(--zing-grid-body-border, 0)Styles the left border of grid body
--zing-grid-body-border-rightvar(--zing-grid-body-border, 0)Styles the right border of grid body
--zing-grid-body-border-topvar(--zing-grid-body-border, 0)Styles the top border of grid body
--zing-grid-border1px solid var(--theme-border-color)Styles the border of grid
--zing-grid-border-bottomvar(--zing-grid-border, 1px solid var(--theme-border-color))Styles the bottom border of grid
--zing-grid-border-leftvar(--zing-grid-border, 1px solid var(--theme-border-color))Styles the left border of grid
--zing-grid-border-radius0Applies border radious to grid
--zing-grid-border-rightvar(--zing-grid-border, 1px solid var(--theme-border-color))Styles the right border of grid
--zing-grid-border-topvar(--zing-grid-border, 1px solid var(--theme-border-color))Styles the top border of grid
--zing-grid-box-shadownoneApplies a box shadow behind grid
--zing-grid-color--theme-colorThe font color of grid
--zing-grid-font-family--theme-font-familySets the font family of grid text
--zing-grid-font-size--theme-font-sizeSets the font size of grid text
--zing-grid-font-style--theme-font-styleSets the font style of grid text
--zing-grid-font-weight--theme-font-weightSets the font weight of grid text
--zing-grid-table-border0Styles the border of grid table contents
--zing-grid-table-border-bottomvar(--zing-grid-table-border, 0)Styles the bottom border of grid table contents
--zing-grid-table-border-leftvar(--zing-grid-table-border, 0)Styles the left border of grid table contents
--zing-grid-table-border-rightvar(--zing-grid-table-border, 0)Styles the right border of grid table contents
--zing-grid-table-border-topvar(--zing-grid-table-border, 0)Styles the top border of grid table contents

CSS Selector

Set zing-grid:not(:defined) {display:none;} to hide <zing-grid> instances until they are ready (see below). This stops child elements from appearing unstyled for a brief moment.

zing-grid:not(:defined) {display:none;}

You can also set a height for the grid while it is loading. Implicitly, the grid will add a loading attribute so you can easily style it while it is fetching data.

If you want to prevent choppy rendering, set a height on the grid while it is loading, like so:

zing-grid[loading] {
  height: 450px;
}
On This Page