Theming
Try it live — the theme and density pickers above the grid switch every combination on this page. To design a colour theme of your own instead, start in the Theme Builder.
Two props:
<DataGrid
dataSource={rows}
rowKey="id"
columns={columns}
theme="minimal"
density="compact"
dark={isDark}
/>
Both are optional. Omit theme and the grid renders exactly as it always
has — the packaged look is not one of the six, it is the default, and it is
not going to move under you.
Switching is a class swap on the grid root, so it repaints without rebuilding anything: no re-render of a cell, no reload, and nothing to configure. Bind it to a user preference and it changes as fast as the user clicks.
The six
theme | Character |
|---|---|
minimal | Minimal chrome — no column rules, hairline row rules, roomy radii. For product UIs where the grid sits among cards. |
ledger | Dense and fully ruled — small type, tight padding, near-square corners. For the case where the grid is the application. |
elevated | Tall rhythm, rows-only rules, a medium-weight tracked header, pill controls and real elevation. |
framed | Airy but fully framed, with a doubled rule anchoring the header band. |
kanuni | The KanuniLabs house theme: an ink header carrying the brand gold, over a warm near-white body. |
kanuni-midnight | The house theme in dark. Already dark — it ignores the dark flag. |
Every theme ships a light and a dark palette. dark picks between them, so
one flag drives all six:
<DataGrid theme="elevated" dark={prefersDark} … />
Nothing here is a third-party stylesheet: the palettes, metrics and line work are ours, and each name says what the theme does.
Palettes
A second, independent axis. The theme decides the structure — where the rules are drawn, how tall a row is, how round a control is. A palette decides only the colours:
<DataGrid theme="ledger" palette="nord" dark={isDark} … />
palette | Character |
|---|---|
nord | Arctic, desaturated blue-grey. The calmest — a dense grid of numbers does not vibrate. |
dracula | Near-black violet with high-chroma purple and pink. |
solarized | The fixed-lightness classic, designed as a matched light/dark pair. |
gruvbox | Warm retro, high contrast — the only genuinely warm light mode here. |
catppuccin | Pastel, with very close surface tones. Easy over a long reading session. |
tokyo-night | Deep navy with violet and cyan; the most saturated dark. |
The two multiply: theme="ledger" palette="nord" is Ledger's dense ruled grid
in Nord's arctic blues, and theme="elevated" palette="nord" is Elevated's tall
airy one in the same blues. Six themes and six palettes is thirty-six looks out
of twelve class names. A palette on its own recolours the packaged default.
Each ships a light and a dark set, so dark keeps working across all of them.
These are the colour schemes people already know from their editors. The hues are theirs; the mapping onto the grid's tokens — which colour becomes the header, the stripe, the accent, the thing that has to stay readable on the accent — and the contrast work that mapping needs are ours. No third-party stylesheet is involved. Where a scheme publishes only a dark set, the light counterpart is our own reading of the same hue family, and the stylesheet says so at that block.
Colour schemes
Thirty-six more colour sets on the same palette prop, built differently from
the six above: each is a handful of seed colours — page, cell, ink, accent and
optionally a header band — from which every token is derived and then
measured. Text is pushed until it reaches 4.5:1 on the surface it sits on, an
accent and a focus ring until they reach 3:1, so a scheme cannot ship a muted
label or an invisible focus ring.
Each scheme is one mode, light or dark, and carries it with it: dark does not
flip a scheme, the scheme decides. Pick a dark one for a dark app.
They come as separate stylesheets so you load only what you use. Load them
after styles.css:
import '@kanunilabs/datagrid-react/styles.css';
import '@kanunilabs/datagrid-react/themes/graphite.css';
// or every scheme at once (~57 KB):
// import '@kanunilabs/datagrid-react/themes/all.css';
<DataGrid theme="minimal" palette="graphite" density="compact" … />
The vanilla package ships the same files under @kanunilabs/datagrid/themes/
and takes the same option:
import '@kanunilabs/datagrid/styles.css';
import '@kanunilabs/datagrid/themes/linen.css';
createGrid(host, { …, theme: 'ledger', palette: 'linen' });
A scheme recolours every surface the grid draws — the header band, rows,
stripes, selection and range, totals and group rows, the filter and column
menus, the editor and its validation message, the chart panel (its series are
derived from the scheme's accent, as below), the status bar and dialogs.
Structure stays with theme: theme="ledger" palette="corporate" keeps
Ledger's ruled, dense layout under Corporate's ink header.
palette | Mode | Family | Character |
|---|---|---|---|
porcelain | Light | neutral | Crisp white, cool ink and a clear blue — the everyday default. |
ivory | Light | neutral | Warm off-white with a bronze accent; quiet and premium. |
stone | Light | neutral | Warm greys and a graphite accent — low noise, high polish. |
mist | Light | cool | Cool grey surfaces and a steel-blue accent for analytical work. |
glacier | Light | cool | Blue-grey header band over white cells, a deep sky accent. |
slate | Light | cool | Light slate surfaces with an indigo-slate accent; technical and calm. |
linen | Light | warm | Cream cells and a sage accent; natural and soft for long sessions. |
sandstone | Light | warm | Sand and beige with a terracotta accent. |
taupe | Light | warm | Soft grey-brown neutrals and a cocoa accent; understated. |
azure | Light | colorful | A blue-tinted header band and a confident blue accent. |
indigo | Light | colorful | White cells under a lavender band, an indigo accent. |
teal | Light | colorful | Fresh mint band and a deep teal accent. |
lagoon | Light | colorful | Cyan-washed surfaces and an ocean accent. |
emerald | Light | colorful | Green-tinted band and an emerald accent; good for finance. |
orchid | Light | colorful | Soft violet band and a vivid violet accent. |
rose | Light | colorful | A blush band and a muted crimson accent. |
amber | Light | colorful | Honey band and an amber accent; warm and bright. |
coral | Light | colorful | Peach band and a coral-orange accent. |
corporate | Light | specialty | An ink header band over white cells; boardroom-formal. |
editorial | Light | specialty | Paper white and deep red, like a printed report. |
monochrome | Light | specialty | Pure greyscale: no hue anywhere, the accent is ink. |
contrast-light | Light | specialty | Black on white with strong rules, for low vision and bright rooms. |
charcoal | Dark | neutral | Neutral charcoal with a soft blue accent; the everyday dark. |
graphite | Dark | neutral | Mid-grey graphite and a silver-blue accent; gentle contrast. |
onyx | Dark | neutral | Soft black for OLED screens, with a lilac accent. |
slate-night | Dark | cool | Deep slate and a sky accent — technical and cool. |
steel | Dark | cool | Blue-grey steel surfaces and a cornflower accent. |
midnight | Dark | colorful | Navy depth with a bright blue accent. |
indigo-night | Dark | colorful | Indigo-tinted dark and a periwinkle accent. |
forest | Dark | colorful | Deep green-black with an emerald accent. |
deep-sea | Dark | colorful | Dark teal water and an aqua accent. |
aubergine | Dark | colorful | Plum-dark surfaces with a soft violet accent. |
burgundy | Dark | colorful | Wine-dark and a rose accent; warm for a dark. |
ember | Dark | colorful | Brown-black with a glowing amber accent. |
contrast-dark | Dark | specialty | White on black with bright rules and a yellow accent. |
terminal | Dark | specialty | Green-on-black for dense, data-heavy monitoring screens. |
The list is exported, so a picker never drifts from what is installed:
import { COLOR_SCHEMES } from '@kanunilabs/datagrid-core';
// [{ id: 'porcelain', name: 'Porcelain', mode: 'light', family: 'neutral', description: '…', seed: {…} }, …]
Your own scheme
The derivation is public. Give it seeds and it returns the tokens; turn those
into --dg-* properties and set them on the grid's container — no class, no
CSS file:
import { deriveSchemeTokens, dataGridSchemeVars } from '@kanunilabs/datagrid-core';
const tokens = deriveSchemeTokens(
{ background: '#f4f1ea', surface: '#fffdf8', text: '#1d1a14', accent: '#0f6b5c' },
'light',
);
<div style={dataGridSchemeVars(tokens)}>
<DataGrid … />
</div>
Inline properties on a wrapper reach the grid itself; popups are portalled to
<body> and do not inherit them. For a scheme that also covers menus and
dialogs, write the stylesheet instead — dataGridSchemeCss('acme', tokens)
returns it, for palette="acme" — or build one in the
Theme Builder, which exports that CSS, a JSON file to import
again later, and the PivotGrid equivalent.
schemeContrastChecks(tokens) returns the nineteen contrast pairs the packaged
schemes are tested against, each with its measured ratio, so your own can be
held to the same floor.
Density
density is 'compact' | 'normal' | 'comfortable', and it is not a font-size
switch. Row height, header height, cell padding, control heights, toolbar and
pager padding and the filter field all move together, so the proportions hold:
compact | normal | comfortable | |
|---|---|---|---|
ledger | 20px rows, 11px type | 25px, 12px | 32px, 13px |
minimal | 26px, 12px | 36px, 13px | 44px, 14px |
elevated | 32px, 13px | 40px, 14px | 52px, 15px |
Each theme scales from its own normal rather than a shared table — Elevated starts at 40px and Ledger at 25px, and one common compact value would have flattened the presets into each other at that density.
An explicit rowHeight still wins over both props. Density is a shorthand, not
an override.
Charts follow the theme
When a theme is set, the chart panel derives its series colours from that theme's accent instead of a fixed palette — so an Elevated grid does not draw its first bar in someone else's blue. The first series is the accent; the rest are hue rotations of it that keep its saturation and lightness, which is what makes a dark theme's series come out light enough for a dark canvas.
The colours are resolved to literals rather than left as var(), for two
reasons that both bite: recharts writes the colour as an SVG presentation
attribute, which does not support var(), and PNG/SVG export serializes the
chart into a standalone file with no stylesheet behind it.
Without a theme, the packaged eight are used, unchanged.
Writing your own
A theme here is a set of CSS custom property overrides and nothing else.
Everything the stylesheet draws with — every colour, metric, shadow and border —
is read through a --dg-* property, so a theme never restyles a component and
can never fall behind one.
Yours is a name, passed to the same theme prop the packaged ones use:
<DataGrid theme="acme" rowHeight={30} … />
The grid turns it into the class kanuni-datagrid-theme-acme and puts that
class on every surface it draws — the grid itself, the Enterprise wrapper (chart
panel, status bar, filter and edit strips) and every popup and dialog, which are
portalled to <body> and could not inherit a class through the cascade. Write
the tokens on the three roots those surfaces carry, exactly as the packaged
themes do:
.kanuni-datagrid-root.kanuni-datagrid-theme-acme,
.kanuni-datagrid-enterprise.kanuni-datagrid-theme-acme,
.kanuni-datagrid-detached.kanuni-datagrid-theme-acme {
--dg-surface: #fffdf8;
--dg-surface-header: #f4efe4;
--dg-border: #e4dccb;
--dg-text: #1b1811;
--dg-primary: #8a6d2f;
/* What sits ON the accent. Set it: white on a light accent is unreadable,
and this is the token that decides a chip label and a primary button. */
--dg-on-primary: #ffffff;
--dg-row-height: 30px;
--dg-header-height: 34px;
/* A whole shorthand, so a theme can drop a rule entirely rather than fade it. */
--dg-cell-border: none;
}
The two-class selectors matter: each root declares the default tokens itself, so a single-class rule wins or loses by stylesheet order alone.
One caveat with --dg-row-height: the virtualizer computes every row offset and
the scroll extent from the row height, so it has to reach the engine as a
number. A custom theme has no preset row height — set rowHeight alongside your
CSS, or use density, and the two stay in agreement.
className is not the channel for a theme. It lands on the grid root only:
not on the Enterprise wrapper, not on any popup. Keep it for layout — size,
margin, a border around the grid. (Earlier versions of this page said to theme
through className; that styled the grid and left its popups, and on
EnterpriseDataGrid its chart panel and status bar, in the default palette.)
The tokens
Surfaces — --dg-bg, --dg-surface, --dg-surface-hover,
--dg-surface-stripe, --dg-surface-header, --dg-group-bg, --dg-footer-bg,
--dg-selected-bg, --dg-overlay
Header band — --dg-header-bg, --dg-header-text,
--dg-header-text-muted, --dg-header-hover, --dg-header-weight,
--dg-header-transform, --dg-header-tracking, --dg-header-font-size
The header is deliberately separate from --dg-surface-header: they default to
the same value, but an ink header still wants a light group panel, filter row
and footer.
Text and accent — --dg-text, --dg-text-muted, --dg-primary,
--dg-primary-soft, --dg-on-primary, --dg-focus-ring
Status — --dg-danger, --dg-danger-text, --dg-on-danger,
--dg-success, --dg-success-text, --dg-on-success, --dg-warning.
Each colour comes as a set: the bare token is a fill (a badge, a "saved"
mark), -text is the same colour deepened (or, in dark palettes, lifted) to
read as text on the cells, and --dg-on- is the text that sits on the fill.
Every packaged palette and colour scheme sets all three, measured at 4.5:1.
Typeface — --dg-font-family. Not declared by the stylesheet: unset, the
grid inherits the page's font. Set it once and the grid, the Enterprise chrome
and every popup portalled to <body> use it — a font set only on the grid's
container would not reach those popups.
:root {
--dg-font-family: 'Inter', system-ui, sans-serif;
}
Numbers line up whatever the font: number cells, totals, the row-number column
and the pager use equal-width digits (font-variant-numeric: tabular-nums).
Line work — --dg-border, --dg-border-strong, --dg-cell-border,
--dg-row-border, --dg-header-cell-border, --dg-header-border
Metrics — --dg-row-height, --dg-header-height, --dg-cell-padding-x,
--dg-font-size, --dg-radius, --dg-radius-control, --dg-control-height,
--dg-control-font-size, --dg-filter-input-height, --dg-chrome-font-size,
--dg-chrome-padding-y
Elevation — --dg-shadow-popup, --dg-shadow-popup-sm,
--dg-shadow-menu, --dg-shadow-card, --dg-shadow-panel,
--dg-shadow-dialog, --dg-shadow-pinned, --dg-shadow-pinned-right
Scrollbar — --dg-scrollbar-thumb, --dg-scrollbar-track. Only applied
when a theme is set; an unthemed grid keeps the platform scrollbar.
Theme Builder
The Theme Builder designs a colour theme on the real grids. Start from one of the 36 packaged colour schemes, change any of its seed colours — background, cells, text, accent, header band, borders, status colours — and the DataGrid and PivotGrid beside it follow, menus and filter popups included. Contrast is measured on every change, and colours the theme had to deepen to stay readable are listed.
It exports three files under the id you give the theme:
-
CSS — the DataGrid palette block and the PivotGrid
data-themeblock. Load it after the grid stylesheets and pass the id:<DataGrid palette="acme" … /> <BasePivotGrid theme={{ id: 'acme' }} … /> -
JSON — the theme definition (seed, mode and any pinned tokens). Import it back into the builder to keep editing.
-
PivotGrid
themeobject — the same colours for an app that sets them from code.
The preview on that page is drawn with the same generated stylesheet the CSS
export contains. Structure (theme) and density stay separate props and are
not part of the export.
Contrast
Every packaged theme and palette clears WCAG AA (4.5:1) on the surfaces that carry text, measured rather than assumed, and the floor is pinned by a test so a colour cannot be nudged for looks and quietly drop below it.
The thirty-six colour schemes are held to nineteen pairs each — text on the page and on cells, stripes, hovered and selected rows and totals; muted text on cells and panels; header text, plain and muted; the accent on cells and on the header band; the focus ring; the label on the accent and on the danger fill; error, success and warning text; search highlights. A test also fails if two schemes of the same mode come out too close to tell apart.
Three palettes needed a correction to get there, which is the point of measuring rather than trusting the source scheme: Nord's muted red left its own label at 4.31:1, Gruvbox's light yellow sits at 3.33:1 on its cream ground, and Tokyo Night Day's keyword blue is a keyword colour rather than a body ink and measured 4.03:1 on the header. Each was moved within its own hue family.
--dg-on-primary is the one to be careful with in a theme of your own. It is
what sits on the accent — a group chip's label, a primary button's text — and
the house theme is the case that proves it: the KanuniLabs gold is #c5a55a,
and white on it measures 1.9:1. Set the token, do not inherit it.
Cost
None on the render path. The browser resolves custom properties during style computation, so a themed grid does no more work per cell than an unthemed one, and there is no per-cell React work of any kind — the theme is one class on the root, composed once per grid.