Documentation

Theming

Try it live:

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

themeCharacter
minimalMinimal chrome — no column rules, hairline row rules, roomy radii. For product UIs where the grid sits among cards.
ledgerDense and fully ruled — small type, tight padding, near-square corners. For the case where the grid is the application.
elevatedTall rhythm, rows-only rules, a medium-weight tracked header, pill controls and real elevation.
framedAiry but fully framed, with a doubled rule anchoring the header band.
kanuniThe KanuniLabs house theme: an ink header carrying the brand gold, over a warm near-white body.
kanuni-midnightThe 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} … />
paletteCharacter
nordArctic, desaturated blue-grey. The calmest — a dense grid of numbers does not vibrate.
draculaNear-black violet with high-chroma purple and pink.
solarizedThe fixed-lightness classic, designed as a matched light/dark pair.
gruvboxWarm retro, high contrast — the only genuinely warm light mode here.
catppuccinPastel, with very close surface tones. Easy over a long reading session.
tokyo-nightDeep 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.

paletteModeFamilyCharacter
porcelainLightneutralCrisp white, cool ink and a clear blue — the everyday default.
ivoryLightneutralWarm off-white with a bronze accent; quiet and premium.
stoneLightneutralWarm greys and a graphite accent — low noise, high polish.
mistLightcoolCool grey surfaces and a steel-blue accent for analytical work.
glacierLightcoolBlue-grey header band over white cells, a deep sky accent.
slateLightcoolLight slate surfaces with an indigo-slate accent; technical and calm.
linenLightwarmCream cells and a sage accent; natural and soft for long sessions.
sandstoneLightwarmSand and beige with a terracotta accent.
taupeLightwarmSoft grey-brown neutrals and a cocoa accent; understated.
azureLightcolorfulA blue-tinted header band and a confident blue accent.
indigoLightcolorfulWhite cells under a lavender band, an indigo accent.
tealLightcolorfulFresh mint band and a deep teal accent.
lagoonLightcolorfulCyan-washed surfaces and an ocean accent.
emeraldLightcolorfulGreen-tinted band and an emerald accent; good for finance.
orchidLightcolorfulSoft violet band and a vivid violet accent.
roseLightcolorfulA blush band and a muted crimson accent.
amberLightcolorfulHoney band and an amber accent; warm and bright.
coralLightcolorfulPeach band and a coral-orange accent.
corporateLightspecialtyAn ink header band over white cells; boardroom-formal.
editorialLightspecialtyPaper white and deep red, like a printed report.
monochromeLightspecialtyPure greyscale: no hue anywhere, the accent is ink.
contrast-lightLightspecialtyBlack on white with strong rules, for low vision and bright rooms.
charcoalDarkneutralNeutral charcoal with a soft blue accent; the everyday dark.
graphiteDarkneutralMid-grey graphite and a silver-blue accent; gentle contrast.
onyxDarkneutralSoft black for OLED screens, with a lilac accent.
slate-nightDarkcoolDeep slate and a sky accent — technical and cool.
steelDarkcoolBlue-grey steel surfaces and a cornflower accent.
midnightDarkcolorfulNavy depth with a bright blue accent.
indigo-nightDarkcolorfulIndigo-tinted dark and a periwinkle accent.
forestDarkcolorfulDeep green-black with an emerald accent.
deep-seaDarkcolorfulDark teal water and an aqua accent.
aubergineDarkcolorfulPlum-dark surfaces with a soft violet accent.
burgundyDarkcolorfulWine-dark and a rose accent; warm for a dark.
emberDarkcolorfulBrown-black with a glowing amber accent.
contrast-darkDarkspecialtyWhite on black with bright rules and a yellow accent.
terminalDarkspecialtyGreen-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:

compactnormalcomfortable
ledger20px rows, 11px type25px, 12px32px, 13px
minimal26px, 12px36px, 13px44px, 14px
elevated32px, 13px40px, 14px52px, 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-theme block. 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 theme object — 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.