Styling model
Understand the layers you restyle the grid with, from theme tokens to plugin overlays, and which layer to pick for a given change.
The grid ships no design layer of its own. It renders shadcn theme tokens, so restyling the grid starts with your theme. When a token is not enough, you go one layer deeper. Pick the shallowest layer that does the job.
Styling layers
The layers run from the least effort to the most:
- Theme tokens. The grid colors resolve to shadcn tokens such as
--background,--border,--muted, and--primary. Change a token in your:rootand.darkblocks, and the whole grid follows in light and dark mode. - CSS variables. The grid reads variables such as
--grid-column-border,--grid-pin-shadow, and--grid-scroll-shadow, each with a fallback. The grid writes--grid-row-heightitself from therowHeightordensityprop ofDataGridRoot. - Data-attribute CSS. The grid stamps attributes such as
data-active,data-editing,data-pinned,data-search-match, anddata-hoveredon its elements. Select them in plain CSS to style a state, with no React involved. - Class merges.
classNameonDataGridRootmerges after the built-in classes, so your utility wins a conflict. The same holds forgetRowClassNameandgetCellClassNameonDataGridRoot, and forcellClassNameandheaderClassNameon a column. A column'scellClassNamemerges aftergetCellClassName, so the column wins a conflict. Both callbacks receive aCellClassNameCtxwith the value, the row, the row id, the column, and the view row index. - Content replacement.
renderCellon a column,renderHeaderCellonDataGridHeader,renderMarker,emptyState, andloadingStatereplace what the grid draws. They change the content and not the style. - Plugin overlays. The
Overlaymember of a plugin paints your own layer above the cells. See Plugin overlays.
This CSS underlines the cells that match the quick search:
[role="grid"] [data-search-match] {
text-decoration: underline;
}The same rule as a Tailwind class on the root:
import { DataGrid } from "@/components/data-grid/data-grid";
export function Grid() {
return (
<DataGrid
className="h-80 [&_[data-search-match]]:underline"
defaultData={[]}
columns={[]}
/>
);
}Choose a layer
- Re-brand the grid with the theme tokens. One change in
--primaryre-colors the selection, the active-cell ring, the resize handle, and the loading bar. - Change a size or a line with a CSS variable or a prop.
- Style by state with data attributes. Do not select the grid's own utility classes, because class names can change in any release. A data attribute changes only with a Breaking: entry in the changelog.
- Style one column or one row with a class merge.
- Only when classes cannot express the change, reach for content replacement.
Why it works this way
The grid paints with semantic tokens and uses no palette utility. It keeps your radius, base color, font, and spacing, so it matches the rest of your app without a grid-specific theme.
Related
Cell type model
Understand how one cell type object drives display, editing, clipboard, sort, search, and filter, and which rules keep a custom type safe.
State and view index
Learn how the grid addresses rows and columns by data index, view index, and id, which APIs take which address, and why a view index goes stale.