--- title: "ZingGrid Web Component: `` | API Docs" description: "View our in depth tutorial covering the web component `` tag and the associated features for the JavaScript grid." url: https://www.zinggrid.com/docs/api/tags/zing-grid --- ```text experiment_id: web-retrieval-v1 fixture_id: /docs/api/tags/zing-grid.md mode: provenance representation: markdown origin_response_id: 48955aae5b7027ed83450ab51153f331 version: 2026-10-21 version_created_at_utc: 2026-10-21T20:42:35.656Z version_nonce: 6d27be3527470a1b4fc923fe919a912c generated_at_utc: 2026-10-25T01:54:54.406Z response_nonce: ce148a7fab8968bfef55dc1f286b3af4 ``` # `` [Interactive Storybook Playground](https://storybook.zinggrid.com/?path=/docs/components-zing-grid--docs) `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](https://storage.googleapis.com/zinggrid-pwa.appspot.com/components/v2/zing-grid-web-component-dom.png "Image of the DOM relationship for the zing-grid web component tag") | Component | Relationship | Type | Ancestor | | --- | --- | --- | --- | | [ZGBatchEdit](https://www.zinggrid.com/docs/api/tags/zg-batch-edit) | Child | Generated | n/a | | [ZGCaption](https://www.zinggrid.com/docs/api/tags/zg-caption) | Child | Manual | n/a | | [ZGCard](https://www.zinggrid.com/docs/api/tags/zg-card) | Child | Manual | n/a | | [ZGColgroup](https://www.zinggrid.com/docs/api/tags/zg-colgroup) | Child | Generated, Manual | n/a | | [ZGData](https://www.zinggrid.com/docs/api/tags/zg-data) | Child | Manual | n/a | | [ZGDialog](https://www.zinggrid.com/docs/api/tags/zg-dialog) | Child | Generated, Manual | n/a | | [ZGFilterMenu](https://www.zinggrid.com/docs/api/tags/zg-filter-menu) | Child | Generated | n/a | | [ZGFooter](https://www.zinggrid.com/docs/api/tags/zg-footer) | Child | Generated, Manual | n/a | | [ZGFrozenColgroup](https://www.zinggrid.com/docs/api/tags/zg-frozen-colgroup) | Child | Generated | n/a | | [ZGHeader](https://www.zinggrid.com/docs/api/tags/zg-header) | Child | Generated | n/a | | [ZGLoadMask](https://www.zinggrid.com/docs/api/tags/zg-load-mask) | Child | Generated, Manual | n/a | | [ZGMenu](https://www.zinggrid.com/docs/api/tags/zg-menu) | Child | Generated, Manual | n/a | | [ZGPager](https://www.zinggrid.com/docs/api/tags/zg-pager) | Child | Generated, Manual | n/a | | [ZGStatus](https://www.zinggrid.com/docs/api/tags/zg-status) | Child | Generated | n/a | | [ZGTable](https://www.zinggrid.com/docs/api/tags/zg-table) | Child | Generated | n/a | | [ZGTooltip](https://www.zinggrid.com/docs/api/tags/zg-tooltip) | Child | Generated | n/a | #### Related Web Components - [``](https://www.zinggrid.com/docs/api/tags/zg-column/) - [``](https://www.zinggrid.com/docs/api/tags/zg-param/) ## Attributes A lot of features on the root web component `` are enabled just by their presence. Some attributes require values and those are defined under **Example Values**. **Example Usage** ```html ``` ### aggregate Adds aggregate column and sets the type-aggregate-value to the specified value - Type: String - Accepted values: "sum", "avg", "max", "min", "count", "tokenized string" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/21U0IS7T) ### align Aligns the contents of the grid's text - Type: String - Default: `"left"` - Accepted values: "center", "left", "right" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/6FILWB1Y) ### batch-edit Presence of attribute indicates the grid allows batch editing and displays the controls. In batch edit mode, changes can be made to cells that do not have edit disabled or are not a part of the "recordkey" column. - Type: Boolean - Default: `false` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/ZX34SZ4C) ### batch-edit-status Sets the message to display when making batch edits. Can use the following tokens: [[changes]], [[deleted]], [[fieldsEdited]], [[inserted]], [[modified]], [[recordsEdited]]. Can append 'Message' to any of the above for a string description. - Type: String - Default: `"[[changesMessages]]"` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/GSFBMZGE) ### button-tooltip-disabled Turns off the tooltips on all buttons in the grid - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/KBQ43E4K) ### caption The caption for the grid - Type: String - Default: `""` - Accepted values: "My Caption" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/O52C484H) ### card Specifies the defined `` of the grid. More appropriate to use `` in most cases or set the property programmatically. - Type: Object - Default: `[]` - Accepted values: {"renderer-template": "renderTemplate", "editor-template": "editorTemplate", "renderer": "custom-renderer", "editor": "customEditor"} - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/7FSHTJSA) ### cell-break 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. - Type: String - Default: `"normal"` - Accepted values: "all", "ellipsis", "normal", "word" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/A46O96IK) ### cell-class Adds a class to each `` in the grid. This attribute can be applied to both `` or ``. If the attribute is applied to both, ``'s `cell-class` overwrites ``'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`. - Type: String - Default: `""` - Accepted values: "userClassName", "functionName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/7QHJW15H) ### cell-editor Turns cell editing on or off. Automatically turned on when setting `editor` or `editor-controls`. - Type: String | Boolean - Default: `false` - Accepted values: "disabled" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/RJ9FDW1F) ### cell-focus Turns off keyboard nav cell focus if set to disabled - Type: String - Accepted values: "disabled" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/YHMJUU1B) ### cell-tooltip-action Sets the execution method of custom 'icon' type tooltips to either activate on hover or click of the icon - Type: String - Default: `"hover"` - Accepted values: "click", "hover" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/EFSY4YCV) ### cell-tooltip-delay 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. - Type: Number - Default: `1000` - Accepted values: 2000 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/DFHNBLQH) ### cell-tooltip-icon Specifies the icon to use for the info column types - Type: String - Default: `info` - Accepted values: 'checkmark' - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/P56L5RR9) ### cell-tooltip-position Sets the tooltip-position for the cell - Type: String - Default: `"top"` - Accepted values: "top", "left", "right", "bottom" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/VI7LVJZV) ### cell-tooltip-renderer Gets the name of the user's custom render function, on window, to use the function's return value as the tooltip content - Type: String - Default: `""` - Accepted values: "functionName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/L5VON3SE) ### cell-tooltip-template Points to an external template element to be used as the template for the tooltip display - Type: String - Default: `""` - Accepted values: "myTemplateId" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/H0TL7Q4M) ### cell-tooltip-type 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 ``. - Type: String - Default: `default` - Accepted values: "default", "system" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/70BE60YN) ### col-class Adds a class to each `` in targeted ``. 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. - Type: String - Default: `""` - Accepted values: "userClassName", "functionName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/5K4WJTVV) ### column-drag Enables column dragging - Type: String - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/ZJ3ZEZOQ) ### column-drag-action 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. - Type: String - Default: `false` - Accepted values: "reorder", "hide", "both" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/I0Z4308I) ### column-resizable Presence of attribute turns on column resizing for all columns. This excludes internal column types (), which requires setting ZGColumn[resizable] on the column. - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/6QN88PG9) ### column-resizable-max-width Sets the maximum width columns can be set to when resizing - Type: Number - Default: `n/a` - Accepted values: 150 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/2K5XRF7T) ### column-resizable-min-width Sets the minimum width columns can be set to when resizing - Type: Number - Default: `n/a` - Accepted values: 150 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/X5AKZ5HL) ### column-resizable-persistent Presence of attribute displays column resizing for all columns without hover - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/ARYGKYST) ### column-width Sets the width each of the columns - Type: String | Number - Default: `fit` - Accepted values: "fit", "fitheader", "fitcontent", "stretch", "10%", "150px", 150 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/HFAWU3EU) ### columns Specifies the columns of the grid. More appropriate to use `` in most cases or set the property programmatically. - Type: Object - Default: `[]` - Accepted values: [{"index": "firstName"}, {"index": "lastName"}] - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/EU02P5CF) ### columns-control Presence of attribute turns on the menu to show and hide columns - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/0R0WHLV3) ### compact Augments internal themes to a compact mode - Type: Boolean - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/XQU3BZA0) ### config Used to set multiple grid properties at once. This should never be used directly. This is meant for object instantiation. - Type: Object - Default: `{}` - Accepted values: {"search": true,"pager":true,"caption": "Actors/Actresses","pageSize": 5} - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/DCO6DQ23) ### confirm-delete Turns off delete confirmation if set to disable - Type: String - Default: `true` - Accepted values: "disabled" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/1P30R7BU) ### confirmations Sets which confirmation dialogs to display on batch editing and deleting - Type: String - Default: `"all"` - Accepted values: "batch-edit", "batch-edit-discard", "delete", "disabled", "all" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/N2XQIGWB) ### context-menu Enables the default `` context menu or set to the id name of a custom ``. If set to a custom menu and `` 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. Can also set to `"browser"` to use the browser's built in context-menu Note that the `"browser"` context-menu cannot be used together with a custom static-menu. - Type: String | Boolean - Default: `""` - Accepted values: N/A, "browser", "myCustomMenu" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/XSUBCM96) ### creator Sets the create editor to modal (default) or inline. - Type: String - Default: `false` - Accepted values: "inline" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/ZUH4NYL0) ### data Data for the grid presented as an array or object - Type: Object - Default: `""` - Accepted values: [{"firstName": "John", "lastName": "Doe"}] - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/EV3X7J4E) ### default-display The data to display in each cell where the data value is null or undefined - Type: String - Default: `""` - Accepted values: "N/A" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/63IMORRK) ### dialog Sets `` to display dialog and mask within the grid dimensions instead of the whole screen - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/XINAL854) ### dir The HTML standard direction to indicate direction of grid's columns and text - Type: String - Default: `"ltr"` - Accepted values: "ltr", "rtl" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/LKG20E1U) ### editor Turns on the grid editor. Enables single cell editing via double click. Sets the editor to inline (default) or modal. - Type: String | Boolean - Default: `false` - Accepted values: "modal" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/3C61DMKN) ### editor-controls Adds columns for the editor controls. If it is added, default is "all". - Type: String | Boolean - Default: `false` - Accepted values: "editor", "remover", "creator", "all" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/L3U440X5) ### editor-disabled-fields Comma separated list of indexes to turn off editor functionality on. Mimes the functionality of ["editor=disabled"] on `` - Type: String - Default: `""` - Accepted values: fieldIndex - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/4LRZNXI2) ### filter Enables filtering for all columns. Can be turned on/off individually via column. Can be set to "inline" or "menu" Default is "menu" - Type: Boolean - Default: `"menu"` - Accepted values: "menu", "inline", "both", "disabled" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/4HCRN4FI) ### filter-buttons Comma separated list of buttons to display in the specified order on the filter menu - Type: String | Array - Default: `"reset, apply"` - Accepted values: "reset", "close", "apply" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/CHM0EJ01) ### filter-conditions The list of conditions to present as options in the filter menu condition select. Use "break" to display the horizontal separator. Use "default" to use the built in default. - Type: String - Default: `default` - Accepted values: "none", "empty", "notEmpty", "equals", "notEquals", "beginsWith", "endsWith", "contains", "notContains", "between", "notBetween", "greaterThan", "greaterEqualThan", "lessThan", "lessEqualThan", "before", "after", "betweenDate", "today", "yesterday", "tomorrow", custom filter name, "break", "default", "trueVal", "falseVal" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/E460972W) ### filter-conditions-display Number of conditions to display in the filter menu on menu open - Type: Number - Default: `1` - Accepted values: 2 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/PP8PO0EY) ### filter-conditions-max Max number of conditions to display in the filter menu - Type: Number - Default: `1` - Accepted values: 5 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/JR4N4DCR) ### filter-default-condition The condition to initially display on filter menu open - Type: String - Default: `"contains"` - Accepted values: "none", "empty", "notEmpty", "equals", "notEquals", "beginsWith", "endsWith", "contains", "notContains", "between", "notBetween", "greaterThan", "greaterEqualThan", "lessThan", "lessEqualThan", "before", "after", "betweenDate", "today", "yesterday", "tomorrow", custom filter name - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/ZS7YWQS7) ### filter-menu-areas The areas to display in the filter menu. Can be conditions, selectbox, or both - Type: String - Default: `"conditions"` - Accepted values: "conditions", "selectbox", "both" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/863QAY2V) ### filter-on Determines if the filter comparison should be against the raw values or the rendered. This only applies to conditionals in the filter menu. For iframe column type, it is restricted to raw values. For aggregate column type, it is restricted to rendered values. - Type: String - Default: `depends on column type` - Accepted values: "raw", "rendered" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/T007SEBG) ### filter-selectbox-display Determines if the selectbox in the filter menu should display the values as raw or rendered values. - Type: String - Default: `depends on column type` - Accepted values: "raw", "rendered" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/YKJUE5A3) ### filter-trigger Action that fires the filter event from the filter menu. - Type: String - Default: `"button"` - Accepted values: "button", "change" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/OD0KX134) ### foot-class Adds a class to each `` in the ``. 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. - Type: String - Default: `""` - Accepted values: "userClassName", "functionName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/4RSYZH9X) ### frozen-columns-left Sets the number of columns to freeze to the left - Type: Number - Default: `0` - Accepted values: 1 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/ERBCTU9W) ### frozen-columns-right Sets the number of columns to freeze to the right - Type: Number - Default: `0` - Accepted values: 1 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/SHSGTE6C) ### frozen-row-class Adds a class to each `` 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`, `rowParent`, and returns a string which is the class name to apply. - Type: String - Default: `""` - Accepted values: "userClassName", "functionName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/8HIA1NX8) ### frozen-rows-bottom Sets the number of rows to freeze to the bottom - Type: Number - Default: `0` - Accepted values: 1 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/YK9OTK0N) ### frozen-rows-top Sets the number of rows to freeze to the top - Type: Number - Default: `0` - Accepted values: 1 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/YYZBW5QJ) ### gridlines Sets vertical, horizontal or both grid lines to the grid - Type: String - Accepted values: "both", "horz", "horizontal", "vert", "vertical" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/9XDBFP79) ### group-by Sets the index fields to group on. - Type: String - Accepted values: "country" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/LUNDRSXW) ### head-class Adds a class to each `` in the ``. 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. - Type: String - Default: `""` - Accepted values: "userClassName", "functionName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/3X5995IT) ### header-auto-format 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. - Type: String - Default: `""` - Accepted values: "disabled", "functionName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/DXI75TPI) ### header-row-hide Hides any header rows - Type: String - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/O5I6BB3J) ### header-tooltip-action Sets the execution method of custom 'icon' type tooltips to either activate on hover or click of the icon - Type: String - Default: `"hover"` - Accepted values: "click", "hover" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/H30XQPVF) ### header-tooltip-delay Sets the hover delay in milliseconds before displaying the header tooltip - Type: Number - Default: `0` - Accepted values: 2000 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/GJS825NR) ### header-tooltip-icon Specifies the icon to use for the header tooltip trigger icon - Type: String - Default: `info` - Accepted values: 'checkmark' - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/XTERMUKW) ### header-tooltip-icon-position Sets the tooltip icon position for the tooltip icon in the header cells - Type: String - Default: `"right"` - Accepted values: "left", "right", "after-text" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/USHB9WFZ) ### header-tooltip-position Sets the tooltip-position for the header cell - Type: String - Default: `"top"` - Accepted values: "top", "left", "right", "bottom" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/BKMIOSJI) ### header-tooltip-renderer Gets the name of the user's custom render function, on window, to use the function's return value as the tooltip content - Type: String - Default: `""` - Accepted values: "functionName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/Q5DYAB0L) ### header-tooltip-template Points to an external template element to be used as the template for the tooltip display - Type: String - Default: `""` - Accepted values: "myTemplateId" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/0MGML3OF) ### header-tooltip-trigger Sets what part of the header triggers the tooltip. If set to 'icon', an info icon is added to the header. - Type: String - Default: `text` - Accepted values: "text", "icon" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/I1VOMDTH) ### header-tooltip-type 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 ``. - Type: String - Default: `default` - Accepted values: "default", "system" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/O3AQ5MJM) ### height Sets the height of the grid. If the height is less than the size of the content, scrolling is added to grid body. - Type: String | Number - Default: `inherit` - Accepted values: "500px", "500", 500 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/NG2O8JB3) ### icon-set 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. - Type: String - Accepted values: "fa", "fontawesome", "font-awesome" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/ICU6CTB5) ### lang Sets the language to use for the grid - Type: String - Default: `"en"` - Accepted values: "en" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/ZBX1CFXE) ### layout Sets the grid layout to be either `card` or `row` and adds `` to the grid. The default is based on the size of the user's screen, unless `layout` is set. - Type: String - Default: `""` - Accepted values: "card", "row" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/UK168REV) ### layout-controls When `layout` is set, by default `layout-controls` is enabled. To hide, set `layout-controls` to `disabled`. Presence of this attribute will enable `` even if `layout` is not set. - Type: String | Boolean - Default: `""` - Accepted values: "disabled" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/ZOISX39K) ### loading Presence of attribute adds loading state to grid, which triggers `` to show. This attribute allows styling the height of the grid (via CSS) before the data has loaded in the grid. - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/ZF838GXO) ### loading-text Sets the text to display in the `` on data load - Type: String - Default: `"loading..."` - Accepted values: "ZingGrid is Loading" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/VC607IV8) ### loadmask Set `loadmask="disabled"` to prevent the `` from showing on data load. - Type: String - Default: `""` - Accepted values: "disabled" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/7SW1PDDR) ### nested-data-separator Indicates separator that should be used for nested headers and data paths. By default, the '.' is used: 'fullName.first' Setting to `disabled` will turn off parsing for nested headers and will not look at pathing for data - Type: String - Default: `"."` - Accepted values: "/", "disabled" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/OR8CFKQB) ### no-data Sets the message that appears in the `` element when there are no records - Type: String - Default: `"There are no records to display."` - Accepted values: "No Records" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/J4VZX23V) ### page-size Sets the number of records or rows to display per page. Can be set only if `pager` is set. - Type: Number - Default: `50` - Accepted values: 10 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/81Z219UH) ### page-size-card Sets the number of cards to display per page when in card mode. Can be set only if `pager` is set. - Type: Number - Default: `page-size value` - Accepted values: 10 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/PX40SN3K) ### page-size-options Sets the options for page size in `zg-option-list`. Can be set only if `pager` is set. - Type: String - Default: `"5,10,50"` - Accepted values: "15,20,35" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/3X4H4PE4) ### page-size-row Sets the number of rows to display per page when in row mode. Can be set only if `pager` is set. - Type: Number - Default: `page-size value` - Accepted values: 10 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/W4XKN314) ### pager Adds pagination functionality and controls to the grid - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/LWCB9C12) ### pager-button-limit Determines max number of page buttons to display. Default is 5. - Type: Number - Default: `5` - Accepted values: 3 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/4RGO3XLK) ### pager-position Sets pager position. Note: `pager` attribute or `` must be present in order to position pager. - Type: String - Default: `"bottom"` - Accepted values: "top", "bottom" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/NZGKTMFN) ### pager-type Determines which type of pagination to use, input or buttons - Type: String - Default: `''` - Accepted values: "button-text", "button-arrows" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/5EXGD7U7) ### params Name/Value pairs of `` values. More appropriate to use `` in most cases. - Type: Object - Default: `{}` - Accepted values: {"idKey": "id", "sortByKey": "_sort", "sortBy": "capital"} - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/CX509ALI) ### preserve-state-id The ID to use as the key in storing the state. Each grid should have a unique ID or else the state data will be shared across grids. - Type: String - Default: `""` - Accepted values: "zg-client-grid" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/760HIL9C) ### preserve-state-load The method to call when state is ready to be retrieved. Must also set preserveStateSave and preserveStateId - Type: String - Default: `"n/a"` - Accepted values: "functionName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/RQVTBRWY) ### preserve-state-options Comma separated list of features to save in state preservation. Options are 'columnfrozen', 'columnposition', 'columnvisibility', 'columnwidth', 'filter', 'rowgroup', 'layout', 'page', 'pagesize', 'rowfrozen', 'rowgroup', 'rowselector', 'search', 'selector', 'sort' NOTE: If columnfrozen is set, then columnposition will implicitly be set as well - Type: String - Default: `"all"` - Accepted values: "sort, filter, search" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/R372W0RN) ### preserve-state-save The method to call when state is ready to be saved. Must also set preserveStateLoad and preserveStateId. - Type: String - Default: `"n/a"` - Accepted values: "functionName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/RQVTBRWY) ### record-count Sets the total record count. Useful for `loadByPage` when the response packet does not return total count of records. - Type: Number - Default: `""` - Accepted values: 1000 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/QHPET8QF) ### record-duplicate Adds the duplicate control to the end of the row before the edit controls - Type: Boolean - Default: `false` - Accepted values: n/a - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/2J2B950P) ### record-key Adds the record key column to the grid. If set to a string, the string is the header text. - Type: Boolean | String - Default: `false` - Accepted values: "Name" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/JOW2SKTW) ### row-class Adds a class to each `` 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`, `rowParent`, `bodyRowIndex` (1 based), and returns a string which is the class name to apply. - Type: String - Default: `""` - Accepted values: "userClassName", "functionName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/YEF6YEV8) ### row-details-renderer Renderer for the row details component To use a custom renderer, the attribute should be set to the name of the function. The renderer function takes in the following arguments, `recordData`, `domRowDetails`, and `rowObject` The returned value of the renderer function is set as the innerHTML of the zg-row-details component. - Type: String - Default: `""` - Accepted values: "functionName" - Supported versions: 2.x [Example code](https://app.zingsoft.com/demos/embed/WXLCYC8S) ### row-details-template Points to an external template element to be used as the template for the row's details - Type: String - Default: `""` - Accepted values: "myTemplateId" - Supported versions: 2.x [Example code](https://app.zingsoft.com/demos/embed/VZXL4P1R) ### row-height Sets the height of each data row. By default, the body row height is set to 'auto' where it will auto fit the content. If you wish to apply the height to rows besides data row, specify with the `[rowHeightScope]` attribute. - Type: String | Number - Default: `"auto"` - Accepted values: "auto", "48px" - Supported versions: 2.x [Example code](https://app.zingsoft.com/demos/embed/0ABNLHKV) ### row-height-scope If `[rowHeight]` is set, it specifies which rows to apply row height to. Choices are `data`, `headers, and `all`. Can combine with comma separated list - Type: String - Default: `"data"` - Accepted values: "data", "headers", "all" - Supported versions: 2.x [Example code](https://app.zingsoft.com/demos/embed/IJJX1SOW) ### row-selector Adds `selector` type column to the rows as the first column - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/OW6D6ADD) ### search Turns on the search feature and adds `` to the grid. The search button appears in the caption header. - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/JTKMYN3V) ### selector Turns on the selector feature on the grid and adds `` to the grid - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/W591I8MY) ### server-rendered Indicates that the grid was completely rendered on the server and embedded in the page - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/CLJKANYJ) ### sort Enables sorting on all columns. It is possible to disable specific columns via the column's object or setting `sort="disabled"` to specified columns. - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/0LV2QHO9) ### sort-intl Overrides default behavior for international sorting. Turn off international sorting with `sort-intl="disabled"`. - Type: String - Default: `""` - Accepted values: "disabled" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/15S1N2OD) ### sorter 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`. - Type: String - Default: `""` - Accepted values: "functionName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/7UT0EEI4) ### source Defines the source of the data in the grid. Adds the `` element. - Type: String - Default: `""` - Accepted values: "Source: Wikipedia" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/GEEBIRSG) ### src Specifies the absolute or relative URL to fetch data from to populate the grid - Type: String - Default: `""` - Accepted values: "https://url-to-your-api" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/P607ZSA3) ### static-menu Adds a display button that launches the contextmenu. If set to a custom menu and `` 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. Note that custom static-menu cannot not be used together with a `"browser"` context-menu. - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/M8C1YMB8) ### status-delay Changes the duration a status message will remain visible until it automatically closes (in milliseconds) - Type: Number - Default: `"3000"` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/ZFMD4YHD) ### status-persist Prevents status messages from automatically closing after a delay - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/4D5FTJBG) ### status-position Positions the status message in one of nine positions relative to the grid - Type: String - Default: `"top right"` - Accepted values: "top left", "center left", "bottom left", "top center", "center", "bottom center", "top right", "center right", "bottom right", "bar" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/KRKIHPFC) ### template-end-delimiter Defines the regex expression for closing data binding - Type: String - Default: `"]]"` - Accepted values: "}}" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/DRUZJ8JY) ### template-start-delimiter Defines the regex expression for starting data binding - Type: String - Default: `"[["` - Accepted values: "{{" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/DRUZJ8JY) ### theme 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. - Type: String - Default: `"default"` - Accepted values: "android", "black", "default", "dark", "ios", "urlToThemeFile", "customThemeName" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/UAP0KFF1) ### type-selector-page-persist If there is a selector column, it maintains selection between pages. This means that rows can be selected and not on the current page. - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 2.x ### validation-error-message Sets the default validation error message - Type: String - Default: `"Validation Failed"` - Accepted values: "Please provide valid input." - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/Q5IXSMBQ) ### validation-required-message Sets the default validation required message - Type: String - Default: `"Field Required"` - Accepted values: "Please provide valid input." - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/WDVQXHYG) ### viewport Internal attribute. Should not be set. - Type: String - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x ### viewport-pause Keeps current value of `viewport` and freezes the breakpoint - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/JQPB9V1U) ### viewport-stop Removes `viewport` attribute, disabling viewport resizing - Type: Boolean - Default: `""` - Accepted values: N/A - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/1IO1C18N) ### viewport-types 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. - Type: String - Default: `false` - Accepted values: { mobile: 500, test: 600, desktop: 800 } - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/HABTF2ID) ### width Sets the width of the grid. If the width is less than the size of the content, scroll is added to ``. - Type: String | Number - Default: `inherit` - Accepted values: "500", "500px", "5em", "5%", "50vw", 500 - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/MIYZG4F2) ### zebra Presence of attribute adds the classes, `zebra-1` and `zebra-2`, alternating on `` 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. - Type: String - Default: `""` - Accepted values: "userCustomStyle" - Supported versions: 1.x, 2.x [Example code](https://app.zingsoft.com/demos/embed/QXWXL4WD) ## CSS Variables `` can be styled with CSS variables, like so: ```css :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](https://www.zinggrid.com/docs/api/css-variables/reference/) or our [Styling Basics guide](https://www.zinggrid.com/docs/getting-started/styling-basics/) to learn more about styling the grid. | Name | Default | Description | Demo | | --- | --- | --- | --- | | `--zing-grid-background` | #fff | Styles the background of grid | [Example code](https://app.zingsoft.com/demos/embed/S2LGW6WY) | | `--zing-grid-border` | 1px solid var(--theme-border-color) | Styles the border of grid | [Example code](https://app.zingsoft.com/demos/embed/FNVV7TJP) | | `--zing-grid-border-bottom` | var(--zing-grid-border, 1px solid var(--theme-border-color)) | Styles the bottom border of grid | [Example code](https://app.zingsoft.com/demos/embed/BP54E8PI) | | `--zing-grid-border-left` | var(--zing-grid-border, 1px solid var(--theme-border-color)) | Styles the left border of grid | [Example code](https://app.zingsoft.com/demos/embed/BQ8DWU62) | | `--zing-grid-border-radius` | 0 | Applies border radious to grid | [Example code](https://app.zingsoft.com/demos/embed/O84UETSN) | | `--zing-grid-border-right` | var(--zing-grid-border, 1px solid var(--theme-border-color)) | Styles the right border of grid | [Example code](https://app.zingsoft.com/demos/embed/7AFJ7RUL) | | `--zing-grid-border-top` | var(--zing-grid-border, 1px solid var(--theme-border-color)) | Styles the top border of grid | [Example code](https://app.zingsoft.com/demos/embed/PZO08P3O) | | `--zing-grid-box-shadow` | none | Applies a box shadow behind grid | [Example code](https://app.zingsoft.com/demos/embed/58QV7GJW) | | `--zing-grid-color` | --theme-color | The font color of grid | [Example code](https://app.zingsoft.com/demos/embed/PEY7GS10) | | `--zing-grid-font-family` | --theme-font-family | Sets the font family of grid text | [Example code](https://app.zingsoft.com/demos/embed/7KFKVQX1) | | `--zing-grid-font-size` | --theme-font-size | Sets the font size of grid text | [Example code](https://app.zingsoft.com/demos/embed/HCQWBCQ1) | | `--zing-grid-font-style` | --theme-font-style | Sets the font style of grid text | [Example code](https://app.zingsoft.com/demos/embed/9Q837C38) | | `--zing-grid-font-weight` | --theme-font-weight | Sets the font weight of grid text | [Example code](https://app.zingsoft.com/demos/embed/9NIED1XI) | | `--zing-grid-freeze-style-border` | 1px solid #d6e9ff | Styles the border of the frozen column styling element | [Example code](https://app.zingsoft.com/demos/embed/PPZ5PJ0L) | | `--zing-grid-freeze-style-box-shadow` | inset 0 0 6px #99caff | Styles the box-shadow of the frozen column styling element | [Example code](https://app.zingsoft.com/demos/embed/KNJN315S) | | `--zing-grid-table-border` | 0 | Styles the border of grid table contents | [Example code](https://app.zingsoft.com/demos/embed/7AYEIA84) | | `--zing-grid-table-border-bottom` | var(--zing-grid-table-border, 0) | Styles the bottom border of grid table contents | [Example code](https://app.zingsoft.com/demos/embed/V22ON3LN) | | `--zing-grid-table-border-left` | var(--zing-grid-table-border, 0) | Styles the left border of grid table contents | [Example code](https://app.zingsoft.com/demos/embed/TYY11EZ3) | | `--zing-grid-table-border-right` | var(--zing-grid-table-border, 0) | Styles the right border of grid table contents | [Example code](https://app.zingsoft.com/demos/embed/JRSIU7TZ) | | `--zing-grid-table-border-top` | var(--zing-grid-table-border, 0) | Styles the top border of grid table contents | [Example code](https://app.zingsoft.com/demos/embed/U2UPKR02) | ## CSS Selector Set `zing-grid:not(:defined) {display:none;}` to hide `` instances until they are ready (see below). This stops child elements from appearing unstyled for a brief moment. ```css 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: ```css zing-grid[loading] { height: 450px; } ``` ## Slots `` contains placeholders to allow adding markup inside the component. ```html Slotted Content ``` Below is a list of all the associated ZingGrid slots. Check out the [full list of slots](https://www.zinggrid.com/docs/api/styling/css-shadow-parts). | Name | Description | | --- | --- | | (default) | Grid content or configuration that accepts `` elements that are allowed to be manually inserted. |