zing-grid

The main tag used to create JavaScript data grids and data tables. You enable most of the features on this tag, although there are still many features outside of this tag.

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

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 activate features 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>

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

Turns off keyboard nav cell focus if set to disabled

Default Value

No Default Value

Accepted Values

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

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

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

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

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

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

All the associated --zing-grid CSS variables. You can find the full list of css variables or check out our styling basics to learn more about styling the grid.

root: {
  --zing-grid-color: red;
}
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 &lt;zing-grid&gt; instances until they are ready. 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 its loading. Implicitly the grid will add a loading attribute so you can style it while its fetching data very easily.

If you want to prevent screen jank, set a height on the grid while its loading.

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