Theming

The @toolbox-web/grid component is fully themeable via CSS custom properties. Customize colors, spacing, typography, and more without modifying source code.

Quick Start

Override CSS custom properties on the grid element:

tbw-grid {
  --tbw-color-bg: #1a1a2e;
  --tbw-color-fg: #eaeaea;
  --tbw-color-border: #16213e;
  --tbw-color-header-bg: #0f3460;
  --tbw-color-row-hover: #1a1a4e;
}

Scaling with Font Size

All sizing uses em units, so the grid scales proportionally with font-size:

tbw-grid { font-size: 1.25em; }           /* 25% larger */
tbw-grid.compact { font-size: 0.875em; }  /* Compact */

Pre-built Themes

Import a pre-built theme CSS file:

import '@toolbox-web/grid/themes/dg-theme-material.css';

Theme	Description
Standard	Polished, balanced look
Material	Material Design 3 inspired
Bootstrap	Bootstrap 5 styling
Vibrant	Bold purple accents
Contrast	High contrast for accessibility
Large	Larger fonts and spacing

Dark Mode Support

The grid uses light-dark() for automatic theme support:

tbw-grid { color-scheme: light dark; }  /* Auto-adapt */
tbw-grid { color-scheme: dark; }        /* Force dark */

All built-in color variables use light-dark() internally, so they automatically provide appropriate colors for both modes.

CSS Cascade Layers

The grid organizes its styles into CSS cascade layers:

@layer tbw-base, tbw-plugins, tbw-theme;

Your unlayered CSS always wins — no !important needed. This makes theming predictable:

tbw-base — Core grid styles (structure, layout)
tbw-plugins — Plugin-contributed styles (selection highlighting, filter icons, etc.)
tbw-theme — Theme overrides (pre-built themes go here)
(unlayered) — Your custom CSS — always highest priority

Interactive Theme Builder

Use the theme builder below to customize every CSS variable in real-time — including core tokens and plugin-specific variables across all categories. The preview grid updates instantly as you tweak values. Export your theme as a .css file when you’re done.

CSS Variable Reference

The tables below list all 228 CSS custom properties across core styles and every plugin, with their live computed values in this page. Toggle between light and dark mode to see how values change.

The table below shows all CSS custom properties with their current computed values in this page's context. Switch between light and dark mode to see how values change.

Building a Custom Theme

Create a CSS file with your overrides:

@layer tbw-theme {
  tbw-grid {
    --tbw-color-bg: #fafafa;
    --tbw-color-fg: #333;
    --tbw-color-border: #e0e0e0;
    --tbw-color-header-bg: #f5f5f5;
    --tbw-color-header-fg: #555;
    --tbw-color-row-hover: #e3f2fd;
    --tbw-color-accent: #1976d2;
    --tbw-color-focus-ring: #1976d2;
    --tbw-cell-padding: 0.4em 0.75em;
    --tbw-font-family: 'Inter', sans-serif;
  }
}

Import it after the grid:

import '@toolbox-web/grid';
import './my-theme.css';

Programmatic Styles

Since the grid uses light DOM, standard CSS works — global stylesheets, <style> in <head>, or external CSS files can all target elements inside <tbw-grid>.

For styles you need to inject or update from JavaScript at runtime, use the registerStyles() API:

// Inject styles programmatically
grid.registerStyles('my-highlights', `
  .row-warning { background: #fff3e0; }
  .row-error { background: #fce4ec; }
`);

// Remove when no longer needed
grid.unregisterStyles('my-highlights');

Plugin Styles

Plugins inject their own CSS via adoptedStyleSheets in the tbw-plugins cascade layer. You can override any plugin class in your theme:

Plugin	Key CSS Classes	What They Style
Selection	`.tbw-cell-selected`, `.tbw-row-selected`	Selected cells and rows highlight
Editing	`.tbw-cell-editing`, `.tbw-row-dirty`, `.tbw-row-new`	Active editor and dirty tracking indicators
Filtering	`.tbw-filter-active`	Filter icon active state
Grouping	`.tbw-group-row`, `.tbw-group-toggle`	Group header rows and expand/collapse icons
Responsive	`.tbw-card-view`, `.tbw-card-row`	Card layout mode styling

Override in your theme:

@layer tbw-theme {
  tbw-grid .tbw-cell-selected {
    background: rgba(25, 118, 210, 0.15);
  }
  tbw-grid .tbw-row-dirty {
    border-left: 3px solid orange;
  }
}

Icon Customization

The grid uses a CSS-first hybrid icon system with two configuration paths:

Approach	Best for	How it works
CSS variables (default)	Themes, static icons, no-JS customization	Override `--tbw-icon-*` properties on `tbw-grid`
JavaScript (`gridConfig.icons`)	Dynamic icons, icon libraries, runtime changes	Set `icons` in grid config — takes precedence over CSS

CSS is the recommended default — it requires no JavaScript, works with cascade layers, and is tree-shakeable. Use the JS path when you need dynamic icons (e.g., loading from an icon library at runtime) or HTMLElement instances.

All grid icons (sort indicators, expand/collapse, filter, drag handles, etc.) are rendered via CSS custom properties. Override them in your theme.

Text / Emoji Icons

Set the --tbw-icon-<key> variable to any CSS <string> value:

@layer tbw-theme {
  tbw-grid {
    --tbw-icon-sort-asc: '↑';
    --tbw-icon-sort-desc: '↓';
    --tbw-icon-expand: '+';
    --tbw-icon-collapse: '−';
    --tbw-icon-size: 1.2em;
  }
}

SVG Mask Icons

The filter and filter-active icons use SVG masks by default — just override their -mask variable:

@layer tbw-theme {
  tbw-grid {
    --tbw-icon-filter: '';
    --tbw-icon-filter-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z'/%3E%3C/svg%3E");
  }
}

For any other icon, switching to mask mode requires setting the content to '', providing a -mask URL, and adding background: currentColor with explicit dimensions:

@layer tbw-theme {
  tbw-grid {
    /* Set content to '' and provide the mask URL */
    --tbw-icon-sort-asc: '';
    --tbw-icon-sort-asc-mask: url("data:image/svg+xml,...");
  }

  /* Add background + dimensions so the mask is visible (cannot be shipped
     generically because they would affect text/emoji icon layout) */
  tbw-grid [data-icon='sort-asc']:empty::before {
    width: var(--tbw-icon-size, 1em);
    height: var(--tbw-icon-size, 1em);
    background: currentColor;
  }
}

The grid ships mask-image, mask-size, mask-repeat, and mask-position for every icon — you only need to add background: currentColor.

Available Variables

Variable	Default	Description
`--tbw-icon-expand`	`'▶'`	Tree / group / master-detail expand
`--tbw-icon-collapse`	`'▼'`	Tree / group / master-detail collapse
`--tbw-icon-sort-asc`	`'▲'`	Sort ascending indicator
`--tbw-icon-sort-desc`	`'▼'`	Sort descending indicator
`--tbw-icon-sort-none`	`'⇅'`	Unsorted indicator
`--tbw-icon-filter`	`''` (mask)	Column filter icon
`--tbw-icon-filter-active`	`''` (mask)	Active filter icon
`--tbw-icon-submenu-arrow`	`'▶'`	Context menu submenu arrow
`--tbw-icon-drag-handle`	`'⋮⋮'`	Row drag handle
`--tbw-icon-tool-panel`	`'☰'`	Tool panel toggle
`--tbw-icon-print`	`'🖨️'`	Print button

Each icon also has a -mask variant (e.g., --tbw-icon-sort-asc-mask) for SVG mask-based rendering with currentColor.