API Elements

<zing-grid>

The most important tag in the library. Contains most of the attributes to turn grid features on/off. Set zing-grid:not(:defined) {display:none;} to hide <zing-grid> instances until they are ready. This stops child elements from appearing unstyled for a brief moment.

Example Usage

CloseCopy Copied
<zing-grid src="https://cdn.zinggrid.com/datasets/users-small.json">
  Hello ZingGrid
</zing-grid>

<zg-body>

<zg-body> is created dynamically by the ZingGrid library, as such should not be manually added by the developer. However the user can style <zg-body> using CSS.

<zg-button>

A custom, styled button that can be used both for internal grid-related action and for user-specific actions. It is stylable via CSS. Some buttons are automatically inserted when a feature that uses it enabled, like pager, while others are inserted manually by the user.

Example Usage

CloseCopy Copied
<zing-grid>
  <zg-button disabled action="reload"></button>
</zing-grid>

<zg-caption>

A caption can be manually inserted inside the <zing-grid> tag as slotted content or automatically inserted when the caption is enabled. <zg-caption> is stylable via CSS.

Example Usage

CloseCopy Copied
<zing-grid src="https://cdn.zinggrid.com/datasets/users-small.json">
  <zg-caption>
    <h2>Hello World</h2>
  </zg-caption>
</zing-grid>

<zg-card>

The container for a card template that holds a custom template for card mode. This custom template will be rendered per row. <zg-card> can be styled via CSS or the --zg-card-* selectors. Please reference the "Template" section for more details on templates.

<zg-cell>

<zg-cell> is the container for a single cell; it corresponds to the <td> tag on an HTML table. It is automatically inserted and should not be placed directly in the user's HTML. <zg-cell> can be styled via CSS.

Note: these are the cells inside of zg-body, for cells in the column headers see <zg-head-cell>.

<zg-checkbox>

A checkbox is automatically inserted when a feature that uses it is enabled, like <zg-column type="selector">, or it can be manually-inserted to the grid. It can be style via CSS.

Example Usage

CloseCopy Copied
<zing-grid src="https://cdn.zinggrid.com/datasets/users-small.json">
  <zg-checkbox checked></zg-checkbox>
</zing-grid>

<zg-colgroup>

<zg-colgroup> is a container for the columns of the grid specified by <zg-column tags. This element is similiar in function to the <colgroup tag in an HTML element. Developers should always add this element to their grid structure, however ZingGrid will insert it automatically if it is omitted. As an non-visual element you should not apply style to this tag.

Example Usage

CloseCopy Copied
<zing-grid src="https://cdn.zinggrid.com/datasets/users-small.json">
  <zg-colgroup>
    <zg-column index="firstName" header="First"></zg-column>
  </zg-colgroup>
</zing-grid>

Note: Omission of <zg-colgroup may results in a slight performance for autoinsertion.

<zg-column>

The <zg-column> tag is used to associate the columns of the grid to the values in a data set. Attributes on the tag are used to configure both the data type, style and function of the grid column. It is possible to build grids without explict <zg-column> tags and in the case ZingGrid will add a column for each index in the dataset. However, developers are encouraged to explore the features available with <zg-column> to utilize the powerful features ZingGrid has to offer.

Example Usage

CloseCopy Copied
<zing-grid src="https://cdn.zinggrid.com/datasets/users-small.json">
  <zg-column index="firstName" header="First"></zg-column>
</zing-grid>

<zg-control-bar>

The <zg-control-bar> is inserted dynamically by the ZingGrid library and serves as a container for the grid's interface controls. As a generated element, developers should not manually place <zg-control-bar> in their grid, however, they may style the bar and its internal elements using CSS.

<zg-data>

The <zg-data> tag is used to associate a data set with the actual grid. A top-level attribute is placed on <zing-grid> for basic cases, but when more fine grain control is required, <zg-data> should be employed and various configuration values set via the options attribute or more appropriately via <zg-param> tags nested within the tag.

<zg-dialog>

The <zg-dialog> tag is used internally for dialogs used by CRUD (Create, Read, Update, and Delete) actions, as well as allow for custom dialogs to be created for generic use with the grid. The design goal of the custom element is to extend HTML's <dialog> element for a consistent style and more data grid- related duties.

<zg-editor-row>

<zg-editor-row< holds the details of the edit mode for the grid. <zg-editor-row< is created internally and should not be placed directly in the user's HTML.

CloseCopy Copied
<zing-grid src="https://cdn.zinggrid.com/datasets/users-small.json">
  <zg-editor-row type="modal"></zg-editor-row>
</zing-grid>

<zg-focus>

The <zg-focus> element is a generated element added to <zing-grid> when the selector attribute is defined. It is used as a container for the focus of cell(s) and used as a CSS target for styling by the developer. It should not be accessed specifically beyond styling.

<zg-foot>

The <zg-foot> tag contains the foot cells (<zg-foot-cell>) of the data grid specified via the foot-cell attribute found on <zg-column> tags. The tag roughly corresponds to the idea of the <tfoot> tag used in HTML tables. The <zg-foot> tag is generated by the library and should not be placed in a grid manually by a developer, but instead is used as a styling target for CSS.

The <zg-foot> tag contains the foot cells (<zg-foot-cell>) of the data grid specified via the foot-cell attribute found on <zg-column> tags. The tag roughly corresponds to the idea of the <tfoot> tag used in HTML tables. The <zg-foot> tag is generated by the library and should not be placed in a grid manually by a developer, but instead is used as a styling target for CSS.

<zg-head>

The <zg-head> tag contains the head cells (<zg-head-cell>) of the data grid specified via the head-cell attribute found on <zg-column> tags. The tag roughly corresponds to the idea of the <thead> tag used in HTML tables. The <zg-head> tag is generated by the library and should not be placed in a grid manually by a devloper, but instead is used as a styling target for CSS.

<zg-head-cell>

The <zg-head-cell> contains header information for a column and is roughly equivalent to the <th> tag used for HTML tables. The <zg-head-cell> tag is generated by the library and should not be placed in a grid manually by a developer, but can be used as a styling target for CSS.

Note: these are the cells inside of column headers, for cells in the grid body see <zg-cell>.

<zg-header>

<zg-header> is the semantic container placed at the top of the grid to hold various grid items. <zg-header> is created internally and should not be placed directly in the user's HTML. The element can be styled via CSS.

<zg-icon>

<zg-icon> is used to display custom ZingGrid icons within the grid. The icon is set by its name, but can have a different look based on the grid's theme. <zg-icon> is created internally when a feature that uses it is enabled, like pager, but can be included in the grid manually as long as the name attribute exists.

<zg-input>

<zg-input> contains input fields with added ZingGrid specific functionality. The specific functionality can be set via the action attribute.

<zg-layout-controls>

Allows you to switch between normal row mode and condensed card mode for the grid. <zg-layout-controls> is created internally and should not be placed directly in the user's HTML, however the user can style the <zg-layout-controls> using the zg-layout-controls selector.

<zg-load-mask>

The <zg-load-mask> element is used to define the loading overlay that displays on top of the grid before the grid is completely rendered. The element is generally dynamically created, though it is possible to manually define it for a complex loading screen. More appropriate would be to define a simple message and use CSS to style the element.

<zg-menu>

The <zg-menu> element is a container for a custom menu for ZingGrid used as context or static (aka "Hamburger") menu. The element is generally dynamically inserted by the library, though the developer can append of overwrite menu with custom entries. The element can be styled using CSS.

CloseCopy Copied
<zing-grid
  src="https://cdn.zinggrid.com/datasets/users-small.json"
  context-menu="mymenu">
  <zg-menu id="mymenu" replace="true">
    <p>This content replaces the built-in menu</p>
  </zg-menu>
</zing-grid>

<zg-menu-group>

A group wrapper for multiple menu items found in the context menu. ZingGrid dynamically creates this element to hold various <zg-menu-item> tags together for organizational purposes. As it is a visual element, it can be styled via CSS.

<zg-menu-item>

This element defines a single menu item in ZingGrid's context menu defined by <zg-menu. The element is typically dynamically generated, through it can be overwritten by a user's own custom <zg-menu-item> elements. The element can be styled via CSS.

<zg-pager>

An element that contains the UI controls for paging through a grid's data set. The element can be manually placed, though it is more often dynamically inserted when paging is enabled via the pager attribute on the <zing-grid> tag. The element can be styled via CSS.

Example Ussage

CloseCopy Copied
<zing-grid
  src="https://cdn.zinggrid.com/datasets/users-small.json">
  <zg-pager size-options="1,2,3"></zg-pager>
</zing-grid>

<zg-param>

<zg-param> is a non-visual element used to pass the configuration options for the <zg-data> element more cleanly via name-value pairs. The element is not required, though it is preferred, as everything set within a <zg-param> element can also be set directly on <zg-data> via the config attribute. Developers should note that when setting complex values for the value attribute to use JSON encoded balues. Also, as a non-visual element, CSS styling does not apply to <zg-param>.

<zg-row>

<zg-row< is the container for the <zg-cell<, <zg-head-cell< , and <zg-filter< elements. It corresponds to the <tr< tag on an HTML table. The <zg-row< element is created dynamically and should not be placed in the grid by a devloper. However, the element is useful for styling the various rows of the grid using CSS.

The <zg-search> element is used to encapsulate the interface widget necessary for searching the grid -- typically a text field and a button to trigger the search. The element is added dynamically when search is specified and should not be directly inserted by the developer. The element and its contents can be styled using CSS.

<zg-selector-mask>

<zg-selector-mask> is used to wrap the cells during user selection for styling purposes. The element is dynamically added to the grid based upon the presence of the selector attribute on the <zing-grid> element. The element should not be manually inserted, through it can be styled using CSS.

<zg-separator>

<zg-separator> specifies the horizontal bar in the <zg-menu> used for separating items. The element is created dynamically and should not be manually inserted by developers. However, <zg-separator> can be styled using CSS. <zg-separator> is created internally and should not be placed directly in the user's HTML, however the user can style the <zg-separator> using the zg-separator selector.

<zg-source>

<zg-source> is used to source the data in ZingGrid. The element internally wraps any text in a <cite role="any"> tag for proper semantics. The element is stylable with CSS like most ZingGrid elements.

<zg-status>

<zg-source> is used to source the data in ZingGrid. The element internally wraps any text in a <cite role="any"> tag for proper semantics. The element is stylable with CSS like most ZingGrid elements.

<zg-status> has generic CSS variables that control all use cases, as well as specific overrides for its states (success, error, etc.). Generic styles are styled in the form of 'element-property' (--zg-status-background), whereas overrides are 'element-state-property' (--zg-status-success-background). For example, to update the background color of the built-in 'success' state, you'll need to use the more specific variable, since it is already defined in the default template.

<zg-text>

<zg-source> is used to source the data in ZingGrid. The element internally wraps any text in a <cite role="any"> tag for proper semantics. The element is stylable with CSS like most ZingGrid elements.

<zg-text> is a ZingGrid specific text value that is bound to the status of the grid, as defined by the value attribute. The field can be manually inserted by a developer, but is more commonly added by the use of certain grid features, like paging. The element is stylable with CSS.

loadingloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloading