# ZingGrid

```text
experiment_id: web-retrieval-v1
fixture_id: /llms.txt
mode: provenance
representation: text
origin_response_id: adabad3de77b67daadf221a057f4b0b1
version: 2026-10-21
version_created_at_utc: 2026-10-21T21:00:47.511Z
version_nonce: e14731b20b9c7969da9890a1ea5a3cef
generated_at_utc: 2026-10-21T22:57:12.994Z
response_nonce: 5cfe279b5c2e6aef6e5c2791884a0577
```

> ZingGrid is a native web component data grid and data table library for JavaScript applications. One script tag or `npm i zinggrid` gives you a declarative `<zing-grid>` custom element with built-in CRUD, sorting, filtering, search, paging, editing, virtual scrolling, and theming — no framework required, and it works inside React, Vue, Angular, Svelte, Astro, and plain HTML. Free to use with a watermark; licensed builds remove it.

Key facts for generating correct code:

- Version: this file describes ZingGrid v2.x. Older v1-era patterns and attribute names you may have seen in training data can be outdated or wrong; where they conflict with this file or the linked docs, follow these. The [Changelog](https://www.zinggrid.com/docs/change-log) (listed under Optional) is the source of truth for the current release and for any breaking changes.
- The element is `<zing-grid>`. Columns are `<zg-column index="fieldName">` children. All tags are real DOM — if you know HTML, you know ZingGrid.
- Load via CDN: `<script src="https://cdn.zinggrid.com/zinggrid.min.js" defer></script>` or `import ZingGrid from 'zinggrid'`.
- Most features are boolean attributes on the root tag: `sort`, `search`, `pager`, `filter`, `editor-controls`, `selector`, `batch-edit`, `columns-control`.
- Data comes from the `data` attribute (inline JSON), the `src` attribute (any REST URL), or `<zg-data>` with `<zg-param>` children for headers, adapters (GraphQL, Firebase, Supabase, Dexie Cloud; MongoDB and MySQL go through your own REST route), and server-side paging/sorting/filtering.
- Full CRUD against a REST endpoint requires only `src` plus `editor-controls` — create, update, and delete calls are wired automatically.
- Styling uses CSS custom properties (`--zing-grid-*`), CSS shadow parts, and a `theme` attribute. Hide flash-of-undefined-content with `zing-grid:not(:defined) { display: none; }`.
- For license keys and tiers, see [Licensing](https://www.zinggrid.com/docs/guides/licensing) and [Pricing](https://www.zinggrid.com/pricing).
- Minimal working example:
  `<zing-grid caption="Users" search sort pager page-size="10" src="https://cdn.zinggrid.com/datasets/user-roles.json"></zing-grid>`
- JavaScript access: the grid is a plain DOM element, so get it with `querySelector`, call methods directly on it, and listen with native `addEventListener`. Event details are on `e.detail` (`ZGData`, `ZGEvent`, `ZGTarget`). Do not invent methods or event names; look them up in the [Method Reference](https://www.zinggrid.com/docs/api/methods/reference) and [Event Reference](https://www.zinggrid.com/docs/api/events/reference).
  ```js
  const zgRef = document.querySelector('zing-grid');
  zgRef.setData([{ name: 'Ada', role: 'Admin' }, { name: 'Lin', role: 'User' }]);
  zgRef.addEventListener('record:click', (e) => {
    const { ZGData } = e.detail;
    console.log(ZGData);
  });
  ```

## Getting Started

Tutorial path for newcomers. Each page is a short walkthrough; the Data & CRUD section below holds the full reference for the same topics.

- [Your First Grid](https://www.zinggrid.com/docs/getting-started/your-first-grid): Use this when you have never used ZingGrid and need to install it (CDN or npm) and render a first grid
- [Data Basics](https://www.zinggrid.com/docs/getting-started/data-basics): Use this when you want a quick tutorial on loading data into a grid, via inline data or a `src` URL. For specific sources, see the REST, GraphQL, CSV and other pages under Data & CRUD below
- [CRUD Basics](https://www.zinggrid.com/docs/getting-started/crud-basics): Use this for a first REST-backed grid: a short tutorial that wires one endpoint for create, read, update, delete. For full configuration, see [CRUD Guide](https://www.zinggrid.com/docs/crud/basics)
- [Adding Features](https://www.zinggrid.com/docs/getting-started/adding-features): Use this when your grid renders and you want to turn on built-in features with attributes, such as sorting, search, paging, and filtering. These are only the common ones; see the [Features Index](https://www.zinggrid.com/docs/features) for the full list
- [Remote Data](https://www.zinggrid.com/docs/getting-started/remote-data): Use this when you want to read data from a remote URL or a local JSON file with `src`, pick the array out of a nested JSON response with `recordPath`, or refresh the grid from a changing endpoint with `setData()`
- [Styling Basics](https://www.zinggrid.com/docs/getting-started/styling-basics): Use this when you want to change how the grid looks with CSS variables or shadow parts

## Data & CRUD

Reference material. Use these pages after the Getting Started tutorials, when you need every option, adapter, or operation rather than a first working example.

- [REST](https://www.zinggrid.com/docs/data/rest): Use this when configuring a REST endpoint with `<zg-data>` and `<zg-param>` (headers, params, methods, `sortByKey`, `sortDirKey`, `searchKey`, `idKey`)
- [GraphQL](https://www.zinggrid.com/docs/data/graphql): Use this for a GraphQL endpoint. `adapter="graphql"` sends GET or POST requests with bodies built by named functions (`readBody`, or a `bodyMethodSuffix`). Use `recordPath` and `nodePath` to reach the response array, and `headers` for auth
- [Supabase](https://www.zinggrid.com/docs/data/supabase): Use this for Supabase tables. The adapter handles the request format against `/rest/v1/<table>`; supply the API key via `queryString` (`apikey=...`) and the primary-key column via `idKey`. API-key auth only, no user sign-in
- [Firebase](https://www.zinggrid.com/docs/data/firebase): Use this for Firebase Realtime Database URLs (`https://<db>.firebaseio.com/<path>`) with full CRUD. `adapter="firebase"` maps `sortByKey` to `orderBy` and `limitToKey` to `limitTo`, and `loadByScroll` gives server-side infinite scroll. Auth: pass `auth=<ID_TOKEN>` in `queryString`, or use the Firebase SDK adapter (Firestore).
- [Dexie Cloud](https://www.zinggrid.com/docs/data/dexie-cloud): Use this for Dexie Cloud (IndexedDB synced to the cloud). Takes no `src`: register your client with `ZingGrid.registerClient(db)` and name the table with `dataTable`. The only adapter with live sync: `subscription="true"` updates grids across tabs, windows and devices; also register `ZingGrid.registerClient(liveQuery, 'subscription')`
- [MongoDB](https://www.zinggrid.com/docs/data/mongodb): Use this for MongoDB. There is no adapter; the pattern is a Node/Express route that returns the collection as a JSON array, which the grid reads via `src`. Mongo's `_id` field appears as a column unless you define columns with `<zg-column>`. Paging, sorting and filtering are done client-side
- [MySQL](https://www.zinggrid.com/docs/data/mysql): Use this for MySQL. There is no adapter; either a Node/Express route returns rows as JSON for `src`, or PHP encodes rows with `json_encode` and assigns them to the grid's `data` property. Paging, sorting and filtering are done client-side
- [CSV](https://www.zinggrid.com/docs/data/csv): Use this when your data is in a CSV file or string, with the `csvHeader`, `csvDelimiter`, `csvCaption` and `responseType` params
- [HTML Table](https://www.zinggrid.com/docs/data/html-table): Use this when you already have a `<table>` and want to upgrade it to a grid, using `data-zg-*` attributes such as `data-zg-head-row`, `data-zg-hidden` and `data-zg-pager`
- [CRUD Guide](https://www.zinggrid.com/docs/crud/basics): Use this as the reference for full CRUD configuration across all operations, either after [CRUD Basics](https://www.zinggrid.com/docs/getting-started/crud-basics) or when you need more than the default wiring
- [Create](https://www.zinggrid.com/docs/crud/create): Use this when configuring how new records are added, with the `createOptions` param
- [Read](https://www.zinggrid.com/docs/crud/read): Use this when configuring how records are loaded with the `readOptions`, `header` and `recordPath` params
- [Update](https://www.zinggrid.com/docs/crud/update): Use this when configuring how records are edited and saved, with the `updateOptions` param
- [Delete](https://www.zinggrid.com/docs/crud/delete): Use this when configuring how records are removed, with the `deleteOptions` param
- [Customizing Endpoints](https://www.zinggrid.com/docs/guides/customizing-your-endpoints): Use this when your REST API is non-standard and you need to map its URLs, methods, or payloads, using params such as `sortByKey`, `searchKey` and `pageKey`, or `ZingGrid.registerAdapter()`

## API Reference

- [Tag Usage Guide](https://www.zinggrid.com/docs/api/tags/usage): Use this when you need to know which tags nest inside which (`<zing-grid>`, `<zg-column>`, `<zg-data>`, `<zg-param>`) and how they fit together in markup
- [API Introduction](https://www.zinggrid.com/docs/api/intro): Use this when you are new to the API and want to know whether a task belongs to tags/attributes, methods, events, or styling before opening the matching reference
- [Slots](https://www.zinggrid.com/docs/api/slots): Use this when you want to inject your own markup into the grid, such as custom toolbar, header, footer or empty-state content, and need the available slot names
- [`<zing-grid>`](https://www.zinggrid.com/docs/api/tags/zing-grid): Use this for the root element: all attributes (`sort`, `filter`, `pager`, `page-size`, `selector`, `editor`, `layout`, `theme`, and more), CSS variables, and slots
- [`<zg-column>`](https://www.zinggrid.com/docs/api/tags/zg-column): Use this for column definitions: `index`, `type`, `header`, `renderer`, `editor`, `filter`, `sort-asc`, `sort-desc`, `head-cell`, `foot-cell`
- [`<zg-data>`](https://www.zinggrid.com/docs/api/tags/zg-data): Use this for the data configuration element: `src`, `data`, `adapter`, `options`
- [`<zg-param>`](https://www.zinggrid.com/docs/api/tags/zg-param): Use this for name/value parameters that configure data fetching, such as `loadByPage`, `loadByScroll`, `recordPath`, `header`, and `createOptions`/`readOptions`/`updateOptions`/`deleteOptions`
- [Method Reference](https://www.zinggrid.com/docs/api/methods/reference): Use this for the programmatic API on the grid object, such as `getData()`, `setData()`, `setGroupBy()`, `lastPage()`, `setPageSize()`, `sortColumn()`
- [Method Usage](https://www.zinggrid.com/docs/api/methods/usage): Use this when you need to know how to get the grid element and call methods on it (timing after `grid:ready`, arguments, return values). For the list of methods, see [Method Reference](https://www.zinggrid.com/docs/api/methods/reference)
- [ZingGrid Object](https://www.zinggrid.com/docs/api/methods/zinggrid-object): Use this for the global ZingGrid object and utilities: `registerEditor()`, `registerCellType()`, `registerFilterer()`, `registerAdapter()`, `setLicense()`
- [Event Reference](https://www.zinggrid.com/docs/api/events/reference): Use this for grid lifecycle, data, and interaction events, such as `grid:ready`, `grid:select`, `grid:sort`, `grid:pagechange`, `record:click`, `cell:click`, `data:load`
- [Event Usage](https://www.zinggrid.com/docs/api/events/usage): Use this when you need to wire up a handler and read `e.detail` (`ZGData`, `ZGEvent`, `ZGTarget`), or cancel/inspect an event. For the list of event names, see [Event Reference](https://www.zinggrid.com/docs/api/events/reference)
- [CSS Variables](https://www.zinggrid.com/docs/api/styling/reference): Use this when you need the exact name of a `--zing-grid-*` or `--zg-*-*` CSS variable to change a color, font, spacing, size, etc.
- [Styling Usage](https://www.zinggrid.com/docs/api/styling/usage): Use this when you need to know where to set `--zing-grid-*` or `--zg-*-*` variables (global, per grid, or per theme) so they take effect. For variable names, see [CSS Variables](https://www.zinggrid.com/docs/api/styling/reference)
- [CSS Shadow Parts](https://www.zinggrid.com/docs/api/styling/css-shadow-parts): Use this to style internals with `::part()`, such as `::part(header)` and `::part(body)`
- [Theming System](https://www.zinggrid.com/docs/api/styling/theming-system): Use this for built-in and custom themes via the `theme` attribute (`default`, `android`, `ios`)

## Guides & Features

- [Column Guide](https://www.zinggrid.com/docs/guides/column): Use this when you are setting up columns and need to choose between auto-generated and explicit `<zg-column>`, or to hide, reorder, size or rename columns
- [Data Types](https://www.zinggrid.com/docs/guides/data-types): Use this for built-in column `type` values (currency, date, image, emoji, and more)
- [HTML Templates](https://www.zinggrid.com/docs/guides/html-templates): Use this for custom cell rendering inside `<zg-column>` with `[[index]]` binding tokens and `<template>`
- [Using JavaScript](https://www.zinggrid.com/docs/guides/using-javascript): Use this when the grid is already on the page and you need to change it at runtime: `setAttribute()`, `zgRef.setData()`, querying child elements, or listening to events like `grid:ready`. To create a grid from JavaScript, see [Object Basics](https://www.zinggrid.com/docs/guides/object-basics)
- [Attribute vs Element](https://www.zinggrid.com/docs/guides/attribute-vs-element): Use this when a feature can be set two ways and you need to know which to use and which wins when they disagree, e.g. `caption` vs `<zg-caption>`. The attribute drives the element (one-way sync), so update the attribute at runtime
- [Component Basics](https://www.zinggrid.com/docs/guides/component-basics): Use this when you are writing the grid in HTML and want the basic pattern: simple (attributes on `<zing-grid>`) vs complex (nested child tags like `<zg-data>` and `<zg-caption>`). Start here if you are new to ZingGrid markup
- [Object Basics](https://www.zinggrid.com/docs/guides/object-basics): Use this when you want to create the grid from JavaScript with `new ZingGrid(selector, config)` instead of writing `<zing-grid>` in HTML, including the constructor arguments and defining columns and data as objects. To modify a grid that already exists, see [Using JavaScript](https://www.zinggrid.com/docs/guides/using-javascript)
- [Using CSS](https://www.zinggrid.com/docs/guides/using-css): Use this when you want to style the grid with ordinary CSS selectors or inline `style` on `<zing-grid>` and `<zg-caption>`, and need to know what is reachable from outside the shadow DOM. For variables and `::part()`, see [Styling Basics](https://www.zinggrid.com/docs/getting-started/styling-basics) and [CSS Shadow Parts](https://www.zinggrid.com/docs/api/styling/css-shadow-parts)
- [Mobile First Grids](https://www.zinggrid.com/docs/guides/mobile-first-grids): Use this for responsive card/row layouts and viewport breakpoints (mobile, tablet-portrait, tablet-landscape, desktop, desktop-large)
- [Features Index](https://www.zinggrid.com/docs/features): Use this to browse every per-feature page, including ones not listed individually below
- [Sorting](https://www.zinggrid.com/docs/features/sorting): Use this for column sorting: `sort` attribute, `sort-asc` / `sort-desc` on `<zg-column>`, custom `sorter`, `grid:sort` event
- [Filtering](https://www.zinggrid.com/docs/features/filtering): Use this for column filters: `filter` attribute (`menu`, `inline`, `summary`, `all`, `both`, `disabled`), `filterer`, `filter-key`, `filter-index`
- [Paging](https://www.zinggrid.com/docs/features/paging): Use this for paging: `pager` attribute or `<zg-pager>`, `page-size`, `page-size-options`, `page-size-card`, `pager-type`, `pager-position`; server paging with `<zg-param name="loadByPage">`
- [Selection](https://www.zinggrid.com/docs/features/selection): Use this for row and cell selection: `selector` attribute, `<zg-column type="selector">`, `grid:select` event
- [Editing](https://www.zinggrid.com/docs/features/editing): Use this for editing: `editor` attribute (`inline`, `modal`), `editor-controls`, `editor-template`, `confirm-delete`, `ZingGrid.registerEditor()`
- [Exporting Data](https://www.zinggrid.com/docs/features/exporting-data): Use this to export data with `getData()`, `getData({csv:true})`, `getData({headers:true})`, `getData({cols:"visible"})`
- [Virtual Scrolling](https://www.zinggrid.com/docs/features/virtual-scrolling): Use this for infinite scrolling of large datasets: `height` and `page-size` attributes plus `<zg-param name="loadByScroll" value="true">`
- [Row Grouping](https://www.zinggrid.com/docs/features/row-grouping): Use this to group rows: `group-by` attribute, `<zg-column type="row-group">`, `group-head-cell`, `setGroupBy()` / `getGroupBy()`
- [Aggregation](https://www.zinggrid.com/docs/features/aggregation): Use this for column summaries with `type="aggregate"`, `type-aggregate-value`, `head-cell`, and `foot-cell` (`avg`, `count`, `min`, `max`, `sum`)
- [Conditional Formatting](https://www.zinggrid.com/docs/features/conditional-formatting): Use this to style rows, columns and cells by value with `row-class`, `col-class`, `cell-class`
- [Batch Editing](https://www.zinggrid.com/docs/features/batch-editing): Use this when users need to edit several records at once (`batch-edit` attribute)
- [Drilldown Grids](https://www.zinggrid.com/docs/features/drilldown-grids): Use this when a row should expand to show a related grid
- [Nested Content](https://www.zinggrid.com/docs/features/nested-content): Use this when a row should expand to show extra content beneath it
- [Frozen Rows](https://www.zinggrid.com/docs/features/frozen-rows): Use this when rows should stay pinned while the rest of the grid scrolls
- [Frozen Columns](https://www.zinggrid.com/docs/features/frozen-columns): Use this when columns should stay pinned during horizontal scrolling
- [Grid State Persistence](https://www.zinggrid.com/docs/features/grid-state-persistence): Use this when you need to save and restore the user's grid state, such as sort, filter and column settings
- [Internationalization](https://www.zinggrid.com/docs/features/internationalization): Use this when you need to localize grid text, dates or numbers
- [Server-Side Rendering](https://www.zinggrid.com/docs/features/server-side-rendering): Use this when rendering the grid on the server or in an SSR framework

## Licensing & Pricing

- [Licensing](https://www.zinggrid.com/docs/guides/licensing): Use this for license keys and watermark removal with `ZingGrid.LICENSE` and `ZingGrid.setLicense()`
- [Pricing](https://www.zinggrid.com/pricing): Use this when you need to compare license tiers and prices

## Integrations

All frameworks use the same `<zing-grid>` element; pages differ only in event binding and SSR handling.

- [Vanilla JS](https://www.zinggrid.com/docs/integrations/vanilla-js): Use this when you are working in plain HTML/JS with no build step or framework and want the minimal setup
- [React](https://www.zinggrid.com/docs/integrations/js-frameworks-&-libs/react): Use this when using ZingGrid in React and need to attach event listeners, pass data, or reference the grid element
- [Vue](https://www.zinggrid.com/docs/integrations/js-frameworks-&-libs/vue): Use this when using ZingGrid in Vue and need to register the custom element, bind data, and handle events
- [Angular](https://www.zinggrid.com/docs/integrations/js-frameworks-&-libs/angular): Use this when using ZingGrid in Angular and need to add `CUSTOM_ELEMENTS_SCHEMA`, bind data, and handle events on the `<zing-grid>` element
- [Svelte](https://www.zinggrid.com/docs/integrations/js-frameworks-&-libs/svelte): Use this when using ZingGrid in Svelte and need to bind data and events on the `<zing-grid>` element
- [jQuery](https://www.zinggrid.com/docs/integrations/js-frameworks-&-libs/jquery): Use this when using ZingGrid in a jQuery page and need to select the grid and attach events and data
- [NestJS](https://www.zinggrid.com/docs/integrations/js-frameworks-&-libs/nestjs): Use this when serving a ZingGrid front end from NestJS or backing the grid with a NestJS REST endpoint
- [Astro](https://www.zinggrid.com/docs/integrations/js-frameworks-&-libs/astro): Use this when using ZingGrid in an Astro project and need to load the script and handle client-side rendering
- [Next.js](https://www.zinggrid.com/docs/integrations/js-frameworks-&-libs/nextjs): Use this when using ZingGrid in Next.js and need SSR-safe loading
- [Tailwind CSS](https://www.zinggrid.com/docs/integrations/css-&-design-systems/tailwind-css): Use this when your app uses Tailwind CSS and you need to know how it interacts with the grid's shadow DOM styling
- [Bootstrap](https://www.zinggrid.com/docs/integrations/css-&-design-systems/bootstrap): Use this when you want the grid to match a Bootstrap-styled app's colors and fonts
- [Material Design](https://www.zinggrid.com/docs/integrations/css-&-design-systems/material-design): Use this when you want the grid to match a Material Design look

## Examples

- [Demos Gallery](https://www.zinggrid.com/demos): Use this when you want a working, runnable example of a specific feature to copy from
- [GitHub](https://github.com/ZingGrid/zinggrid): Use this when you need to read the source, check a release, or search or file a bug report
- [Django REST CRUD Example](https://github.com/ZingGrid/zinggrid-django-rest-framework-crud-example): Use this when you want a complete example of a ZingGrid front end doing CRUD against a Django REST Framework backend
- [Storybook Playground](https://storybook.zinggrid.com): Use this when you want to try attributes and options interactively and see the result live

## Optional

- [Features Marketing Overview](https://www.zinggrid.com/features): Use this when you want a marketing-level summary of what ZingGrid offers, not implementation details
- [Changelog](https://www.zinggrid.com/docs/change-log): Use this when you need the current version number, new features, or breaking changes between releases
- [Support](https://www.zinggrid.com/support): Use this when you need to contact the ZingGrid team or find community help
- [Full Documentation](https://www.zinggrid.com/llms-full.txt): Use this as an index of the guide files (getting started, data, guides, integrations, changelog), each fetchable on its own so you load only the topic you need
- [API Reference Index](https://www.zinggrid.com/llms-api.txt): Use this when you need the complete tag, method, event or CSS variable reference; it lists one file per reference page so you can load only what you need