<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

Aligns the contents of all column's cells

Default Value

"left"

Accepted Values

  • "center"
  • "left"
  • "right"
Demo

caption

String

Description

The caption for the grid

Default Value

""

Accepted Values

  • "My Caption"
Demo

card

Object

Description

Specifies the defined <zg-card> of the grid. More appropriate to use <zg-card> in most cases or set the property programmatically.

Default Value

[]

Accepted Values

  • {"rendererTemplate": "renderTemplate", "editorTemplate": "editorTemplate", "renderer": "customRenderer", "editor": "customEditor"}
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

cell-editor

String | Boolean

Description

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

Default Value

false

Accepted Values

  • "disabled"
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

Specifies 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

Enables column dragging

Default Value

""

Accepted Values

  • N/A
Demo

Description

Specifies the action of dragging allowed. By default, if column-drag is enabled then column-drag-action is set "both". This property will turn on column-drag if not already set.

Default Value

false

Accepted Values

  • "reorder"
  • "hide"
  • "both"
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

column-width

String | Number

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 programmatically.

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

Boolean

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

context-menu

String | Boolean

Description

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 menu 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

dialog

Boolean

Description

Sets <zg-dialog> to display dialog and mask within the grid dimensions instead of the whole screen

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

editor

String | Boolean

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"
Demo

editor-controls

String | Boolean

Description

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

Default Value

false

Accepted Values

  • "editor"
  • "remover"
  • "creator"
  • "all"
Demo

filter

Boolean

Description

Enables 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

Sets 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

Converts camel, dash, and kebab case to properly spaced and capitalized typography. Setting to disabled will turn off formatting on headers. 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

Specifies the icon to use for the header tooltip trigger icon

Default Value

info

Accepted Values

  • 'checkmark'
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 | Number

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

String

Description

Allows the user to change the grid icon set to an allowed 3rd-party type (e.g., 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

Description

If setting [icon-set="custom"], points to the custom JSON key/value mapping

Default Value

No Default Value

Accepted Values

No Example Values 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

layout-controls

String | Boolean

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

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

Default Value

50

Accepted Values

  • 10
Demo

Description

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

Default Value

page-size value

Accepted Values

  • 10
Demo

Description

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

Default Value

"5,10,50"

Accepted Values

  • "15,20,35"
Demo

Description

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

Default Value

page-size value

Accepted Values

  • 10
Demo

pager

Boolean

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

Sets pager position. Note: pager attribute or <zg-pager> must be present in order to position pager.

Default Value

"bottom"

Accepted Values

  • "top"
  • "bottom"
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

row-height

String | Number

Description

Sets the height of each row. By default, the row height is set to 'auto' where it will auto fit the content. In the case of frozen columns, the default row height is '48px' because there is a performance hit when using 'auto' with frozen columns.

Default Value

"auto"

Accepted Values

  • "auto"
  • "48px"
Demo

Description

Adds selector type column to the rows as the first column

Default Value

""

Accepted Values

  • N/A
Demo

search

Boolean

Description

Turns on the search feature and adds <zg-search> to the grid. The search button appears in the caption header.

Default Value

""

Accepted Values

  • N/A
Demo

selector

Boolean

Description

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

Enables sorting on all columns. It is possible to disable specific columns via the column's 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

String

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

Adds a display button that launches 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

Prevents status messages from automatically closing after a delay

Default Value

""

Accepted Values

  • N/A
Demo

Description

Positions the status message in one of nine positions relative to the grid

Default Value

"top right"

Accepted Values

  • "top left"
  • "center left"
  • "bottom left"
  • "top center"
  • "center"
  • "bottom center"
  • "top right"
  • "center right"
  • "bottom right"
  • "bar"
Demo

Description

Defines the regex expression for closing data binding

Default Value

"]]"

Accepted Values

  • "}}"
Demo

Description

Defines 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

Description

Sets the default validation error message

Default Value

"Validation Failed"

Accepted Values

  • "Please provide valid input."
Demo

Description

Sets the default validation required message

Default Value

"Field Required"

Accepted Values

  • "Please provide valid input."
Demo

viewport

String

Description

Internal attribute. Should not be set.

Default Value

""

Accepted Values

  • N/A
Demo

Description

Keeps current value of viewport and freezes the breakpoint

Default Value

""

Accepted Values

  • N/A
Demo

Description

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 | Number

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-freeze-style-border1px solid #d6e9ffStyles the border of the frozen column styling element
--zing-grid-freeze-style-box-shadowinset 0 0 6px #99caffStyles the box-shadow of the frozen column styling element
--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