gridcn2.0.0
Contracts

Style contract

Look up the theme tokens, CSS variables, and data attributes that the grid exposes for styling.

The grid paints with your shadcn theme tokens and exposes state as data attributes. Tokens, CSS variables, and data attributes are the contract. The class names that the grid renders can change between versions.

Theme tokens

Every color of the grid resolves to a shadcn token. Change the token in your theme and the grid follows, in light and dark mode.

TokenSurfaces
backgroundThe grid fill and the fill of pinned cells, pinned-row band cells, and marker cells
borderThe grid frame, the bottom border of cells and headers, and the column lines
mutedHeader cells, the row hover tint, the pinned-row band tint, and the loading skeleton
muted-foregroundThe empty state text, the row numbers, the sort indicator, and the column menu trigger
accent and accent-foregroundThe hover tint and the hover text of the column menu trigger
inputThe border of a checkbox cell
primary-foregroundThe check mark of a checked checkbox cell. primary fills and borders that cell
primaryThe selection, the active cell ring, the resize handle, the drop indicator, the fill preview, the loading bar, and the cell flash
destructiveInvalid cells and the validation message

CSS variables

Set a variable on the grid or on any ancestor.

VariableEffectDefault
--grid-pin-shadowColor of the shadows at pinned bandsoklch(0 0 0 / 10%)
--grid-scroll-shadowColor of the edge shadows. transparent hides them--grid-pin-shadow
--grid-shadow-sizeWidth of the side shadows and height of the top and bottom shadows8px
--grid-column-borderColor of the lines between columns. transparent hides them--color-border
--search-highlightColor of the quick search tintA mix of --color-primary
--grid-flash-durationDuration of the cell flash after a fill, an actions.flashCells call, or an update with { flash: true }. 0s turns it off1.2s
--grid-flash-intensityShare of the flash color at the start of the flash24%
--grid-flash-colorColor of the cell flashvar(--color-primary)
--grid-loading-sweep-durationDuration of the loading bar sweep1.2s
--presence-label-foregroundText color of a presence name chipBlack or white, from the user color

The CLI install adds --grid-pin-shadow and --search-highlight to your CSS for light and dark mode. --color-search-highlight also works. If both exist, --search-highlight wins.

The grid writes --grid-row-height itself, from the rowHeight prop or the density preset: 28 pixels for compact, 36 for default, 44 for comfortable. rowHeight wins over density. The headerHeight prop sets the height of a header row. The default is 36. Pass heights as props, because the grid needs the numbers to compute the rendered rows. The variables --grid-scroll-left, --grid-dir, --grid-viewport-width, --grid-content-width, --grid-flash-base, and --grid-search-color are internal and read-only.

Built-in classes

These are the classes that the grid renders and the place where you override them. Class names can change in any release. A data attribute changes only with a Breaking: entry in the changelog. Built-in classes come first in the merge, so a conflicting utility of yours wins.

SurfaceBuilt-in classesOverride
Grid root, [role="grid"]relative touch-manipulation select-none overflow-auto rounded-md border border-border bg-background text-smclassName on DataGridRoot or DataGrid
Header cellgroup relative flex items-center border-b border-border bg-muted px-2 font-medium select-none, plus the column lineheaderClassName on the column
Data cellrelative flex items-center border-b border-border px-2 outline-none, plus the column line, and overflow-hidden except while the cell is in editgetCellClassName, then cellClassName on the column. Every body cell carries an integer z-index, so a z-* class from cellClassName or getCellClassName does not change its stacking. A non-portalled z-index inside a custom cell stays inside that cell
Rowgroup/row data-hovered:bg-muted/50 data-[save-status=saving]:text-muted-foreground data-[save-status=failed]:bg-destructive/10getRowClassName. Pinned and marker cells stay opaque and do not show a row background
Marker cellgroup flex items-center border-b border-border bg-background, plus the column linerenderMarker replaces the content
Marker headerflex items-center justify-center border-b border-border bg-muted, plus the column lineNone
Selection overlaypointer-events-none border border-primary/40 bg-primary/10--primary, or a plugin Overlay
Active cell ringpointer-events-none ring-2 ring-inset ring-primary--primary
Column lineA 1px border at the end side of a column. An end-pinned column has it at the start side instead--grid-column-border
Empty statepointer-events-none absolute inset-0 flex items-center justify-center text-sm text-muted-foregroundThe emptyState prop or labels.grid.emptyState. A filter or a server search that leaves zero rows shows labels.grid.noResults instead
Loading skeletonOne h-4 flex-1 rounded-md bg-muted bar per column. The bars pulse. Under reduced motion they stay stillThe loading flag
Loading barA 2px track bg-primary/20 with a bg-primary sweep. Under reduced motion the sweep is a full-width static bar--primary, --grid-loading-sweep-duration
Validation messagerounded-sm border border-destructive/30 bg-background px-1.5 py-0.5 text-xs text-destructive--destructive
Resize handleAn 8px column with a 3px bg-primary line. The line shows on hover and during a drag--primary
Drop indicatorA 2px --color-primary line at the drag boundary--primary
Fill previewpointer-events-none border border-dashed border-primary bg-primary/5--primary
Sort indicatortext-muted-foreground with a size-3.5 icon. The rank of a multi-sort is text-[0.625rem] tabular-numsDataGridSortIndicator in a custom header
Presence overlayA border and a 12% fill mixed from --presence-color. The name chip is rounded-sm px-1.5 py-0.5 text-xs font-medium shadow-smThe user color, --presence-label-foreground
Pinned-row band cellA 30% muted tint over background, and font-medium--muted

State attributes

Use these in CSS or with the Tailwind data-[attr]: variant.

AttributeElementMeaning
data-activeCellThe active cell
data-editingCellThe cell is in edit mode
data-pinnedCell, header"start" or "end", the pin side
data-pinnedOverlayAn empty value. The overlay segment sits in a pinned zone
data-readonlyCellThe cell is not editable: the grid or its column is readOnly, or the column has no accessorKey and no setValue. Pinned-row cells always carry it
data-typeCellThe cell type key. text is the key of a column with no type
data-search-matchCellThe cell matches the quick search
data-flashCellThe cell flash plays
data-invalidCellThe cell carries a validation error. It also has aria-invalid
data-skeletonCellThe cell stands for an unloaded row
data-grid-pinned-rowCellThe cell belongs to a pinned row band
data-column-idCell, headerThe column id
data-filteredHeaderThe column has an active filter
data-resizingHeaderThe user drags the resize handle
data-draggingHeader, marker cellThe element is the source of a reorder drag
aria-sortHeaderascending, descending, or none
data-row-selectedMarker cellThe row is checked, or a cell range covers it. For checked rows only, style the marker through the isChecked value of renderMarker
data-hoveredRowThe row under the pointer. The mark stays on its row during a scroll. When the scroll stops, it moves
data-save-statusRowsaving while a save is pending, failed after a refusal
data-grid-row-indexRowThe view index of the row
data-row-staleRowA push changed the row in a column that the server sort or filter reads. The mark goes when the server sends the row again
data-gate-pendingRootThe names of the async gates whose promise is pending, separated by spaces

Range, row, and column selection draw as overlay elements, not cell attributes. A selection change does not re-render a cell. These rules style a cell by its state:

[role="grid"] [data-readonly] {
  color: var(--muted-foreground);
}
[role="grid"] [data-save-status="failed"] {
  background-color: color-mix(in oklch, var(--destructive) 10%, transparent);
}

Structural attributes

Each structural element carries one attribute for targeting:

  • Layers: data-grid-header-layer, data-grid-rows-canvas, data-grid-selection-overlay, data-grid-active-cell-overlay
  • Header: data-grid-resize-handle, data-grid-header-menu-trigger, data-grid-column-reorder-handle, data-grid-header-filter-slot, data-grid-header-filter-trigger, data-grid-header-filter-popup, data-grid-header-menu-popup, data-grid-header-dropdown, data-grid-sort-indicator ("asc" or "desc"), data-grid-drop-indicator
  • Touch: data-grid-selection-handle ("start" or "end")
  • Row markers: data-grid-marker-header, data-grid-marker-cell, data-grid-marker-number, data-grid-marker-checkbox, data-grid-reorder-handle
  • Edge shadows: data-grid-pin-shadow ("start", "end", "top", or "bottom") and data-scrolled-start, data-scrolled-end, data-scrolled-top, data-scrolled-bottom on the viewport
  • Loading and empty: data-grid-loading-skeleton, data-grid-loading-bar, data-grid-loading-state, data-grid-empty-state
  • Editors: data-grid-cell-editor on the portaled content of a cell editor
  • Add-ons: data-grid-fill-preview, data-grid-fill-handle, data-grid-presence-overlay, data-grid-presence-label, data-grid-pinned-row-band, data-grid-pinned-row-index, data-grid-context-menu, data-grid-pagination
  • Toolbar: data-grid-toolbar, data-grid-columns-menu, data-grid-search, data-grid-search-count, data-grid-filter-menu, data-grid-filter-count, data-grid-filter-row, data-grid-sort-list, data-grid-sort-row, data-grid-sort-count

On this page