@toolbox-web/grid

@toolbox-web/grid

A high-performance, framework-agnostic data grid built with pure TypeScript and native Web Components. Zero runtime dependencies.

Installation

npm install @toolbox-web/grid

Quick Start

import '@toolbox-web/grid';
import { createGrid } from '@toolbox-web/grid';

const grid = createGrid<Employee>({
  columns: [
    { field: 'name', header: 'Name' },
    { field: 'email', header: 'Email' },
  ],
});
grid.rows = data;
document.body.appendChild(grid);

Factory Functions

Use createGrid<T>() for typed grid creation (avoids manual casting):

import { createGrid, queryGrid } from '@toolbox-web/grid';

// Create a new typed grid
const grid = createGrid<Employee>({
  columns: [{ field: 'name' }],
  features: { selection: 'row' },
});

// Query an existing grid with proper typing
const existing = queryGrid<Employee>('#my-grid');

[!TIP] For complete examples, see the documentation.

Configuration

The grid supports multiple configuration methods, all converging into a single source of truth (effectiveConfig).

Configuration Methods

1. Via gridConfig (recommended for complex setups):

import '@toolbox-web/grid/features/selection';
import '@toolbox-web/grid/features/editing';

grid.gridConfig = {
  columns: [{ field: 'name' }, { field: 'age', type: 'number' }],
  fitMode: 'stretch',
  features: { selection: 'row', editing: true },
  shell: { header: { title: 'My Data Grid' } },
};

2. Via individual properties (convenience for simple cases):

grid.columns = [{ field: 'name' }, { field: 'age' }];
grid.fitMode = 'stretch';

3. Via Light DOM (declarative HTML):

<tbw-grid>
  <tbw-grid-column field="name" header="Name" sortable></tbw-grid-column>
  <tbw-grid-column field="age" header="Age" type="number"></tbw-grid-column>
  <tbw-grid-header title="My Data Grid">
    <tbw-grid-header-content>
      <span>Custom content</span>
    </tbw-grid-header-content>
  </tbw-grid-header>
</tbw-grid>

Precedence

When the same property is set via multiple methods, higher precedence wins:

1. Individual props (fitMode) - highest
2. columns prop
3. Light DOM elements
4. gridConfig property - lowest

Features

API Reference

Element

<tbw-grid></tbw-grid>

HTML Attributes

The grid supports configuration via HTML attributes with JSON-serialized values:

Example with HTML attributes:

<tbw-grid
  rows='[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]'
  columns='[{"field":"id","header":"ID"},{"field":"name","header":"Name"}]'
  fit-mode="stretch"
>
</tbw-grid>

Properties

Methods

Data Methods

Editing Methods (require EditingPlugin)

Focus & Navigation Methods

Column Methods

Shell Methods

Style Methods

Loading Methods

Row Mutation Methods

Animation Methods

Plugin Methods

Events

Core Events

Editing Events (require EditingPlugin)

Use the typed grid.on() API (recommended) or addEventListener with the event name as a string literal — both are type-checked against DataGridEventMap, so typos fail at compile time and event.detail is correctly typed:

import type { DataGridEventMap } from '@toolbox-web/grid';

// Recommended: grid.on() returns an unsubscribe function
const off = grid.on('cell-commit', ({ row, field, newValue }) => {
  saveToServer(row, field, newValue);
});

// Equivalent with addEventListener
grid.addEventListener('cell-commit', (e) => {
  saveToServer(e.detail.row, e.detail.field, e.detail.newValue);
});

Insert & Remove Rows

Add or remove rows at a specific visible position without re-running the sort/filter pipeline:

// Insert with animation (default)
grid.insertRow(3, newEmployee);

// Insert without animation
grid.insertRow(3, newEmployee, false);

// Remove with fade-out animation and await completion
await grid.removeRow(5);

// Remove without animation
const removed = await grid.removeRow(5, false);

Both methods update the source data automatically. The next full grid.rows = freshData assignment re-sorts/re-filters normally. Do not use them for bulk data refreshes — assign grid.rows directly instead.

Row Animation API

All animation methods return Promises that resolve when the animation completes:

// Flash highlight for updated row
await grid.animateRow(5, 'change');

// Animate by row ID
await grid.animateRowById('emp-123', 'change');

// Animate multiple rows
await grid.animateRows([0, 1, 2], 'change');

Note: insertRow and removeRow handle animation automatically — you only need animateRow directly for highlighting existing rows (e.g., after an external data update).

Animation Types: 'change' | 'insert' | 'remove'

Animation Configuration

Configure animation behavior globally:

grid.gridConfig = {
  animation: {
    mode: 'on', // 'on' | 'off' | 'reduced-motion'
    style: 'smooth', // Animation easing (alias for `easing`)
    duration: 200, // Default duration in ms
  },
};

The grid respects prefers-reduced-motion media query automatically when mode is 'reduced-motion'.

Column Configuration

interface ColumnConfig {
  field: string; // Required: property key in row data
  header?: string; // Display label (defaults to field name)
  type?: 'string' | 'number' | 'date' | 'boolean' | 'select';
  width?: number | string; // Pixels, '1fr', or percentage
  sortable?: boolean; // Enable sorting (default: true)
  resizable?: boolean; // Enable resize (default: true)
  editable?: boolean; // Enable editing
  hidden?: boolean; // Initially hidden
  lockVisible?: boolean; // Prevent hiding
  format?: (value: any, row: T) => string;
}

Plugin-Provided Column Properties

Some column properties are added via TypeScript module augmentation when you import a plugin:

See the documentation for complete configuration examples.

Grid Configuration

interface GridConfig {
  columns?: ColumnConfig[];
  fitMode?: 'stretch' | 'fixed';
  features?: Partial<FeatureConfig>; // Declarative feature configuration (recommended)
  plugins?: BaseGridPlugin[]; // Manual plugin instances (advanced)
  icons?: GridIcons; // Centralized icon configuration
  shell?: ShellConfig; // Optional header bar and tool panels
  getRowId?: (row: T) => string; // Custom row ID resolver
  typeDefaults?: Record<string, TypeDefault<T>>; // Type-level column defaults
}

Row Identification

The grid uses row IDs for the Row Update API. By default, it looks for id or _id properties on row objects. Rows without an identifiable ID are not accessible via the Row Update API. For custom ID fields, provide a getRowId function:

grid.gridConfig = {
  columns: [...],
  getRowId: (row) => row.employeeNumber, // Use custom field as ID
};

Icons Configuration

The grid provides a CSS-first hybrid icon system. By default, all icons render via CSS custom properties (see Theming — Icon Customization). For programmatic control or HTMLElement icons, use gridConfig.icons — these take precedence over CSS.

import { DEFAULT_GRID_ICONS } from '@toolbox-web/grid';

grid.gridConfig = {
  icons: {
    expand: '▶', // Collapsed tree/group/detail icon
    collapse: '▼', // Expanded tree/group/detail icon
    sortAsc: '▲', // Sort ascending indicator
    sortDesc: '▼', // Sort descending indicator
    sortNone: '⇅', // Unsorted column indicator
    submenuArrow: '▶', // Context menu submenu arrow
    dragHandle: '⋮⋮', // Column reorder drag handle
  },
};

Icons can be strings (text or HTML) or HTMLElement instances. Plugins use grid-level icons by default but can override with their own config when needed.

Type-Level Defaults

Define column config at the type level that applies to all columns with a matching type. A type default accepts any ColumnConfig property, plus the column properties contributed by whichever plugins you import (editor / editorParams from the editing plugin, filterType from the filtering plugin, and so on).

These six properties are never inherited, because they identify or position a single column: field, header, order, group, hidden, utility.

grid.gridConfig = {
  typeDefaults: {
    country: {
      renderer: (ctx) => {
        const span = document.createElement('span');
        span.textContent = `🌍 ${ctx.value}`;
        return span;
      },
      editor: (ctx) => {
        const select = document.createElement('select');
        ['USA', 'UK', 'Germany'].forEach((c) => {
          const opt = document.createElement('option');
          opt.value = c;
          opt.textContent = c;
          select.appendChild(opt);
        });
        select.value = ctx.value;
        select.onchange = () => ctx.commit(select.value);
        return select;
      },
    },
    currency: {
      editorParams: { min: 0, step: 0.01 },
      width: 120,
      cellClass: 'numeric',
    },
  },
  columns: [
    { field: 'country', type: 'country', editable: true }, // Uses country renderer/editor
    { field: 'salary', type: 'currency', editable: true }, // Uses currency editorParams, width, cellClass
    { field: 'bonus', type: 'currency', width: 200 }, // Column-level width wins
  ],
};

Resolution Priority: Column-level → gridConfig.typeDefaults → Framework adapter → Built-in

Resolution is per-property and shallow: a column keeps any value it defines itself (including falsy ones such as sortable: false), and inherits the type-level value only where it left the property undefined or null.

Framework adapters (@toolbox-web/grid-react, @toolbox-web/grid-angular) provide app-level type registries for React/Angular components.

Plugin Configuration Example

Feature Props (Recommended)

The simplest way to enable plugins is via feature props on gridConfig.features. Import the feature side-effect modules, then set the config declaratively:

import '@toolbox-web/grid/features/selection';
import '@toolbox-web/grid/features/grouping-rows';
import '@toolbox-web/grid/features/filtering';

grid.gridConfig = {
  features: {
    selection: { mode: 'row', multiple: true },
    groupingRows: { groupOn: (row) => row.category, fullWidth: false, aggregators: { total: 'sum' } },
    filtering: { debounceMs: 200 },
  },
};

Each feature import registers a factory; the grid creates the plugin instances from your config. This pattern is tree-shakeable — only imported features are bundled.

[!TIP] For prototyping, import all features at once: import '@toolbox-web/grid/features';

Manual Plugin Instantiation (Advanced)

For full control (e.g., custom plugin subclasses or mixed feature+plugin setups), pass class instances to plugins:

import { GroupingRowsPlugin } from '@toolbox-web/grid/plugins/grouping-rows';
import { SelectionPlugin } from '@toolbox-web/grid/plugins/selection';

grid.gridConfig = {
  plugins: [
    new GroupingRowsPlugin({
      groupOn: (row) => row.category,
      fullWidth: false,
      aggregators: { total: 'sum' },
    }),
    new SelectionPlugin({
      mode: 'row',
      multiple: true,
    }),
  ],
};

Theming

Apply a built-in theme:

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

Available themes: standard, contrast, vibrant, large, bootstrap, material

Custom Theming

Override CSS custom properties on tbw-grid or a parent element:

tbw-grid {
  --tbw-color-bg: #ffffff;
  --tbw-color-fg: #1a1a1a;
  --tbw-color-border: #e5e5e5;
  --tbw-color-header-bg: #f5f5f5;
  --tbw-row-height: 32px;
}

For a complete list of available CSS variables, see grid.css.

Core CSS Variables

Plugin CSS Variables

Plugins define their own CSS variables following a layered fallback pattern:

var(--tbw-{plugin}-{property}, var(--tbw-{global-property}))

This allows you to:

1. Override a specific plugin's style: --tbw-selection-bg
2. Or let it inherit from the global variable: --tbw-color-selection

Example: Customizing the selection plugin

tbw-grid {
  /* Override just the selection plugin's background */
  --tbw-selection-bg: #e0f2fe;

  /* Or change the global selection color (affects all plugins) */
  --tbw-color-selection: #e0f2fe;
}

Common plugin variables:

Check each plugin's styles property for the full list of customizable variables.

Plugins

The grid uses a plugin architecture for optional features. Each plugin has its own documentation:

Creating Custom Plugins

Plugins extend the BaseGridPlugin class:

import { BaseGridPlugin } from '@toolbox-web/grid';
import styles from './my-plugin.css?inline';

interface MyPluginConfig {
  myOption?: boolean;
}

export class MyPlugin extends BaseGridPlugin<MyPluginConfig> {
  readonly name = 'myPlugin';
  override readonly styles = styles; // CSS imported via Vite

  // Default config (override in constructor)
  protected override get defaultConfig(): Partial<MyPluginConfig> {
    return { myOption: true };
  }

  // Called when plugin is attached to grid
  override attach(grid: GridElement): void {
    super.attach(grid);
    // Setup event listeners using this.disconnectSignal for auto-cleanup
  }

  // Called when plugin is detached
  override detach(): void {
    // Cleanup (listeners with disconnectSignal auto-cleanup)
  }

  // Hook: Called after grid renders
  override afterRender(): void {
    // Access DOM via this.gridElement
  }
}

Inter-Plugin Communication

Plugins can communicate with each other using three systems:

1. Event Bus - For async notifications between plugins
2. Query System - For sync state retrieval
3. Broadcast - For events that both external consumers AND other plugins need

Event Bus

Emit and subscribe to plugin events (distinct from DOM events):

import { BaseGridPlugin, type PluginManifest } from '@toolbox-web/grid';

export class MyPlugin extends BaseGridPlugin<MyConfig> {
  // Declare events this plugin emits
  static override readonly manifest: PluginManifest = {
    events: [{ type: 'my-event', description: 'Emitted when something happens' }],
  };

  override attach(grid: GridElementRef): void {
    super.attach(grid);
    // Subscribe to events from other plugins
    this.on('filter-change', (detail) => {
      console.log('Filter changed:', detail);
    });
  }

  private doSomething(): void {
    // Emit to other plugins only (not DOM events)
    this.emitPluginEvent('my-event', { data: 'value' });

    // Emit to both plugins AND external addEventListener consumers
    this.broadcast('sort-change', { sortModel: [...this.sortModel] });
  }
}

Choosing the right emission method:

Query System

Respond to queries from other plugins:

import { BaseGridPlugin, type PluginManifest, type PluginQuery } from '@toolbox-web/grid';

export class MyPlugin extends BaseGridPlugin<MyConfig> {
  // Declare queries this plugin handles
  static override readonly manifest: PluginManifest = {
    queries: [{ type: 'canMoveColumn', description: 'Check if column can be moved' }],
  };

  override handleQuery(query: PluginQuery): unknown {
    if (query.type === 'canMoveColumn') {
      const column = query.context as ColumnConfig;
      if (this.isLocked(column)) return false;
      return undefined; // Let other plugins decide
    }
    return undefined;
  }
}

Querying other plugins:

// Simplified API
const responses = grid.query<boolean>('canMoveColumn', column);
const canMove = !responses.includes(false);

// Or full query object
const responses = grid.queryPlugins<boolean>({
  type: PLUGIN_QUERIES.CAN_MOVE_COLUMN,
  context: column,
});

Built-in query types:

Plugins can also define custom query types for their own inter-plugin communication.

Accessing Plugin Instances

Use grid.getPluginByName() to get a plugin instance for inter-plugin communication or API access:

const selection = grid.getPluginByName('selection');
if (selection) {
  selection.selectAll();
}

TypeScript

All types are exported from the package:

import type { GridConfig, ColumnConfig, CellCommitDetail, BaseGridPlugin } from '@toolbox-web/grid';

Plugin Type Exports

Each plugin exports its class and configuration types from its own entry point:

import { SelectionPlugin, SelectionConfig } from '@toolbox-web/grid/plugins/selection';
import { FilteringPlugin, FilterConfig, FilterModel } from '@toolbox-web/grid/plugins/filtering';
import { TreePlugin, TreeConfig, TreeState } from '@toolbox-web/grid/plugins/tree';

All-in-One Bundle

For convenience, you can import everything from the all-in-one bundle:

import {
  SelectionPlugin,
  FilteringPlugin,
  TreePlugin,
  // ... all other plugins
} from '@toolbox-web/grid/all';

Note: This includes all plugins in your bundle. For smaller bundles, import plugins individually.

Browser Support

Modern evergreen browsers: Chrome/Edge 123+, Firefox 120+, Safari 17.5+. The baseline is driven by the CSS features the default theme relies on (notably light-dark()), not by the Web Components APIs. Popover, CSS anchor positioning and View Transitions are progressively enhanced with automatic fallbacks.

Development

bun run build
bun run test
bun run coverage
bun run start

For architecture details, rendering pipeline, and plugin development, see ARCHITECTURE.md.

Support This Project

This grid is built and maintained by a single developer in spare time. If it saves you time or money, consider sponsoring to keep development going:

What sponsorship enables:

• 🚀 Faster feature development (see ROADMAP)
• 🐛 Priority bug fixes and support
• 📚 Better documentation and examples
• 💼 Corporate sponsors get logo placement and priority support

License

MIT