Theming

GridStorm's visual appearance is controlled entirely through CSS custom properties (CSS variables). You can switch themes at runtime, create custom themes without a build step, and override individual design tokens without touching the grid's source CSS.

Installation

npm install @gridstorm/theme-default

Import the theme in your entry point. This single import includes light, dark, high-contrast, density, RTL, and print styles:

import '@gridstorm/theme-default';

:::example{title="Theme Customization Demo" href="/cookbook/#theme-switching"} Switch between light, dark, and high-contrast themes in real-time. See how CSS custom properties power the theming system. :::

CSS Custom Properties Approach

Every visual property in GridStorm -- colors, spacing, typography, borders, shadows -- is defined as a CSS custom property with the --gs- prefix. These tokens are set on :root and .gs-root, so they cascade naturally through the DOM. To customize the grid, you override the tokens you want to change on the .gs-root element or any ancestor.

Built-in Themes

GridStorm ships three themes out of the box:

Applying a Theme

Set the data-theme attribute on the grid container or any ancestor element:

<div data-theme="dark">
  <div id="my-grid"></div>
</div>

In React, pass the theme prop:

<GridStorm columns={columns} rowData={data} theme="dark" />

Automatic Dark Mode

The default theme includes a prefers-color-scheme: dark media query. If no data-theme attribute is set, the grid automatically uses the dark palette when the user's operating system preference is dark mode.

@media (prefers-color-scheme: dark) {
  :root:not([data-theme]),
  .gs-root:not([data-theme] .gs-root) {
    --gs-color-background: #1e1e2e;
    /* ... all dark tokens applied ... */
  }
}

To opt out of automatic dark mode, explicitly set data-theme="light" on your container.

Complete Token Reference

Colors: Base

Colors: Header

Colors: Row

Colors: Cell

Colors: Overlay

Colors: Popup / Menu

Colors: Grouping

Colors: Floating Filter

Colors: Pagination

Colors: Column Groups

Colors: Column Sidebar

Colors: Scrollbar

Typography

Spacing

Sizing

Borders

Shadows

Z-Index

Transitions

Density Modes

Density modes control vertical spacing, row heights, and font sizes. Apply them with the data-density attribute or a CSS class.

<div data-theme="light" data-density="compact">
  <div id="my-grid"></div>
</div>

RTL Support

GridStorm includes built-in right-to-left support. Set dir="rtl" on the grid container or the <html> element:

<div dir="rtl">
  <div id="my-grid"></div>
</div>

The RTL stylesheet automatically mirrors:

• Header and cell text alignment (right-aligned)
• Sort icon margins
• Group cell indentation and chevron direction
• Pinned column positioning (left/right swap)
• Checkbox cell padding
• Resize handle positioning
• Sidebar positioning
• Pagination layout direction

Print Styles

GridStorm includes a @media print stylesheet that optimizes the grid for printed output:

• The virtual scroll container switches to overflow: visible and height: auto so all rows are printed.
• Rows use position: static and page-break-inside: avoid.
• Colors are forced to light values for readability on paper.
• Non-printable elements are hidden: floating filters, pagination, sidebar, scrollbars, resize handles, context menus, and drag indicators.
• Sticky header positioning is removed.
• Pinned column positioning is removed.

No configuration is needed -- the print styles activate automatically when the user prints the page.

Reduced Motion

When the user has prefers-reduced-motion: reduce set in their operating system, all transitions and animations are disabled:

@media (prefers-reduced-motion: reduce) {
  .gs-root,
  .gs-root * {
    transition-duration: 0ms !important;
    animation-duration: 0ms !important;
  }
}

Custom Theme Creation

Create a custom theme by defining a CSS rule that overrides the tokens you want to change. You only need to override the tokens that differ from the light theme defaults.

.gs-root[data-theme='corporate'],
.gs-theme-corporate .gs-root {
  /* Colors */
  --gs-color-background: #fafaf9;
  --gs-color-foreground: #292524;
  --gs-color-border: #d6d3d1;
  --gs-color-accent: #0284c7;
  --gs-color-accent-hover: #0369a1;

  /* Header */
  --gs-color-header-bg: #f5f5f4;
  --gs-color-header-fg: #44403c;
  --gs-color-header-border: #d6d3d1;

  /* Rows */
  --gs-color-row-bg: #fafaf9;
  --gs-color-row-bg-alt: #f5f5f4;
  --gs-color-row-bg-hover: #e7e5e4;
  --gs-color-row-bg-selected: #e0f2fe;
  --gs-color-row-fg: #292524;

  /* Typography */
  --gs-font-family: 'Inter', sans-serif;
  --gs-border-radius: 4px;
}

Apply it:

<div data-theme="corporate">
  <div id="my-grid"></div>
</div>

Runtime Theme Switching

You can switch themes dynamically without a page reload. Here is a complete example with a theme picker:

import { useState } from 'react';
import { GridStorm } from '@gridstorm/react';

type Theme = 'light' | 'dark' | 'high-contrast';
type Density = 'compact' | 'comfortable' | 'spacious';

function App() {
  const [theme, setTheme] = useState<Theme>('light');
  const [density, setDensity] = useState<Density>('comfortable');

  return (
    <div data-theme={theme} data-density={density}>
      <div>
        <select value={theme} onChange={(e) => setTheme(e.target.value as Theme)}>
          <option value="light">Light</option>
          <option value="dark">Dark</option>
          <option value="high-contrast">High Contrast</option>
        </select>
        <select value={density} onChange={(e) => setDensity(e.target.value as Density)}>
          <option value="compact">Compact</option>
          <option value="comfortable">Comfortable</option>
          <option value="spacious">Spacious</option>
        </select>
      </div>
      <GridStorm columns={columns} rowData={data} height={500} />
    </div>
  );
}

For vanilla JavaScript:

const container = document.getElementById('grid-wrapper')!;

// Switch theme
container.setAttribute('data-theme', 'dark');

// Switch density
container.setAttribute('data-density', 'compact');

// Enable RTL
container.setAttribute('dir', 'rtl');

Scoped Overrides

Override tokens on any ancestor element to create per-section themes without a new theme class:

<div style="--gs-color-accent: #8b5cf6; --gs-color-accent-hover: #7c3aed;">
  <!-- This grid uses a purple accent -->
  <div id="grid-purple"></div>
</div>

<div>
  <!-- This grid uses the default blue accent -->
  <div id="grid-default"></div>
</div>

Next Steps

• React Adapter -- theme prop and runtime switching in React
• Columns -- per-column CSS classes and cell styling
• Architecture -- how the theme system fits into the overall design