Core Features

This page documents built-in grid features that don’t require plugins — the interactive playground, column configuration, data formatting, styling, shell layout, loading states, events, methods, and more.

---

Basic Usage

Interactive Playground

Experiment with the grid’s core options in real time. Adjust the row count, toggle columns, change the fit mode, and enable or disable sortable/resizable columns.

DATA

Row count Number of rows to generate

100

Columns Visible columns

id name active score created role

LAYOUT

Fit mode Column sizing strategy

stretch fixed

FEATURES

Sortable Enable column sorting

Resizable Enable column resizing

Show source

Keyboard Navigation

The grid implements ARIA grid keyboard patterns out of the box — no configuration required:

Key	Action
↑ ↓ ← →	Move between cells
Home / End	Jump to first/last cell in row
Ctrl + Home / Ctrl + End	Jump to first/last cell in grid
PgUp / PgDn	Scroll by viewport height
↵ Enter	Start editing (with EditingPlugin)
Esc	Cancel editing
⇥ Tab / ⇧ Shift + ⇥ Tab	Move to next/previous editable cell

For the full keyboard shortcut reference, see the Accessibility guide.

RTL (Right-to-Left) Support

The grid fully supports RTL languages like Hebrew, Arabic, and Persian. Set dir="rtl" on the grid or any ancestor element — keyboard navigation, column pinning, and layout all adapt automatically.

<tbw-grid dir="rtl"></tbw-grid>

LAYOUT

RTL Enable right-to-left layout

Show source

Logical column pinning: Use pinned: 'start' and pinned: 'end' instead of 'left'/'right' for direction-independent pinning. See the Pinned Columns plugin for details.

---

Configuration

Column Inference

Zero-config data display — Just pass your data and the grid figures out the rest.

When you provide rows without defining columns, the grid automatically:

• Detects fields from the first row’s property names
• Infers data types (string, number, boolean, date) from actual values
• Generates human-readable headers from field names (firstName → First Name)
• Applies appropriate sorting and formatting for each type

grid.rows = myData; // That's it!

Pass data without defining columns — the grid infers everything automatically.

Show source

Light DOM Columns

Declarative configuration — Define columns in HTML instead of JavaScript.

Use <tbw-grid-column> elements (or framework wrapper components) to declaratively define columns directly in your markup:

TypeScript

<tbw-grid>
  <tbw-grid-column field="id" header="ID" width="80"></tbw-grid-column>
  <tbw-grid-column field="name" header="Full Name" sortable></tbw-grid-column>
  <tbw-grid-column field="email" header="Email Address"></tbw-grid-column>
</tbw-grid>

React

import { DataGrid, GridColumn } from '@toolbox-web/grid-react';

function EmployeeGrid({ rows }) {
  return (
    <DataGrid rows={rows}>
      <GridColumn field="id" header="ID" width={80} />
      <GridColumn field="name" header="Full Name" sortable />
      <GridColumn field="email" header="Email Address" />
    </DataGrid>
  );
}

Vue

<script setup lang="ts">
import { TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';
</script>

<template>
  <TbwGrid :rows="rows">
    <TbwGridColumn field="id" header="ID" :width="80" />
    <TbwGridColumn field="name" header="Full Name" sortable />
    <TbwGridColumn field="email" header="Email Address" />
  </TbwGrid>
</template>

Angular

<tbw-grid [rows]="rows">
  <tbw-grid-column field="id" header="ID" width="80"></tbw-grid-column>
  <tbw-grid-column field="name" header="Full Name" sortable></tbw-grid-column>
  <tbw-grid-column field="email" header="Email Address"></tbw-grid-column>
</tbw-grid>

This approach is ideal for:

• Static layouts where columns don’t change at runtime
• Server-rendered pages where HTML is generated on the server
• Template-driven frameworks like Angular or Vue that prefer declarative syntax
• Quick prototyping without writing JavaScript

Define columns declaratively in HTML using <tbw-grid-column> elements.

Show source

Configuration Reference

The grid is configured through the gridConfig property (or individual shorthand properties). The table below covers the most common options — see GridConfig for the full, type-checked reference.

Property	Type	Description
columns	ColumnConfig[]	Column definitions
rows	any[]	Row data array (top-level grid prop, not on GridConfig)
fitMode	FitMode	How columns fill available width ('stretch' or 'fixed')
sortable	boolean	Grid-wide sort toggle (default true)
resizable	boolean	Grid-wide resize toggle (default true)
initialSort	{ field, direction }	Sort applied on first render ('asc' or 'desc')
rowHeight	number | (row, index) => number | undefined	Fixed or variable row heights
getRowId	(row) => string	Unique row identity function
rowClass	(row) => string | string[]	Dynamic row CSS classes
typeDefaults	Record<string, TypeDefault>	Default format/renderer per column type
plugins	GridPlugin[]	Plugin instances
features	Partial<FeatureConfig>	Declarative feature config (alternative to plugins)
columnState	GridColumnState	Saved column state to restore on init
shell	ShellConfig	Shell layout (header, tool panels)
icons	GridIcons	Grid-wide icon overrides
animation	AnimationConfig	Animation defaults (expand/collapse, reorder, etc.)
loadingRenderer	LoadingRenderer	Custom loading indicator
sortHandler	SortHandler	Low-level sort engine override (prefer sortComparator per-column)
gridAriaLabel	string	Accessible label for the grid (aria-label)
gridAriaDescribedBy	string	ID of an element that describes the grid (aria-describedby)
a11y	A11yConfig	Screen reader announcement messages and toggle

Precedence (low → high):

1. gridConfig prop (base)
2. Light DOM elements (declarative)
3. columns prop (direct array)
4. Inferred columns (auto-detected from first row)
5. Individual props (fitMode) — highest

---

Presentation

Value Accessors

Resolve a cell’s value when it isn’t a plain field read. By default the grid reads row[field]. A valueAccessor is only relevant when that’s not the right value — typically because the cell is computed from multiple row fields, plucked from a nested structure, or derived from something outside the row.

You could achieve the visual result with a custom renderer or format function alone, but you’d lose every other feature that depends on knowing what the cell’s value actually is — sorting (unless you also write a sortComparator), filtering (unless you also write a filterValue), grouping, aggregations, copy-to-clipboard, and exports (CSV / Excel) would all see undefined or the raw row[field]. valueAccessor plugs the value in once and every consumer stays consistent.

grid.columns = [
  // Computed from sibling fields
  {
    field: 'total',
    headerName: 'Total',
    valueAccessor: ({ row }) => row.qty * row.price,
  },

  // Pluck from a nested array
  {
    field: 'lastShipmentDate',
    headerName: 'Last Shipment',
    valueAccessor: ({ row }) => row.shipments?.find((s) => s.kind === 'BL')?.date,
    format: (v) => (v ? new Date(v).toLocaleDateString() : '—'),
  },

  // Normalize / coerce
  {
    field: 'name',
    valueAccessor: ({ row }) => `${row.firstName} ${row.lastName}`.trim(),
  },
];

The accessor receives { row, column, rowIndex } and returns the column’s typed value. Use it whenever the cell value isn’t a plain field read.

Precedence

For each operation, the grid looks for a column-level override first, then falls back to the accessor, then to the field:

Operation	Order
Sort comparison	sortComparator → valueAccessor → row[field]
Filter value	filterValue → valueAccessor → row[field]
Group key & aggregations (sum, avg, min, max, first, last)	valueAccessor → row[field]
Copy / export (CSV, Excel)	valueAccessor → row[field] (then format if present)
Display (format / renderer)	valueAccessor → row[field]

This means you write the lookup logic once and every consumer stays consistent.

Caching & invalidation

Accessor results are cached per (row, column.field) in a WeakMap keyed on the row object — so an expensive accessor (e.g. array.find) runs once per row regardless of how many features read it. Primitive rows bypass the cache.

The cache is invalidated automatically when:

• A row reference changes (immutable updates — recommended pattern).
• You call RowManager.updateRow / updateRows / applyTransaction (in-place edits).
• The Editing plugin commits a value.

If you mutate row data outside of those paths, call invalidateAccessorCache(row?, field?) manually:

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

row.shipments.push(newShipment);
invalidateAccessorCache(row, 'lastShipmentDate'); // narrow scope
// or invalidateAccessorCache(row);                // all fields on this row
// or invalidateAccessorCache();                   // entire cache

Reactive accessors (signals / refs / state)

If your accessor closes over reactive state — an Angular signal, a Vue ref, a React store value — the cache won’t notice when that state changes (the row reference is still the same). Pair the accessor with a framework-level effect that invalidates the cache and asks the grid to re-render:

Angular

import { effect, inject } from '@angular/core';
import { invalidateAccessorCache } from '@toolbox-web/grid';

fxRate = signal(1.0);

columns = [{
  field: 'totalUsd',
  valueAccessor: ({ row }) => row.totalEur * this.fxRate(),
}];

constructor() {
  effect(() => {
    this.fxRate(); // tracked dependency
    invalidateAccessorCache();
    this.grid()?.requestRender();
  });
}

Vue

import { ref, watch } from 'vue';
import { invalidateAccessorCache } from '@toolbox-web/grid';

const fxRate = ref(1.0);

const columns = [{
  field: 'totalUsd',
  valueAccessor: ({ row }) => row.totalEur * fxRate.value,
}];

watch(fxRate, () => {
  invalidateAccessorCache();
  gridRef.value?.requestRender();
});

React

import { useEffect } from 'react';
import { invalidateAccessorCache } from '@toolbox-web/grid';

const [fxRate, setFxRate] = useState(1.0);

const columns = useMemo(() => [{
  field: 'totalUsd',
  valueAccessor: ({ row }) => row.totalEur * fxRate,
}], [fxRate]);

useEffect(() => {
  invalidateAccessorCache();
  gridRef.current?.requestRender();
}, [fxRate]);

Editing

Accessors are read-only. Cells driven by a valueAccessor cannot currently be written back through the Editing plugin (a matching valueSetter API is planned). For now, gate them with editable: false or omit editable.

---

Formatters

Transform how values are displayed — Formatters convert raw data values into user-friendly text.

A formatter is a function that receives the cell value and returns a display string:

grid.columns = [
  // Currency
  { field: 'salary', format: (v) => `$${v.toLocaleString()}` },

  // Date
  { field: 'hireDate', format: (v) => new Date(v).toLocaleDateString() },

  // Percentage
  { field: 'progress', format: (v) => `${(v * 100).toFixed(1)}%` },

  // Prefix
  { field: 'id', format: (v) => `#${v}` },
];

Row Styling

Style entire rows based on data using the rowClass callback:

grid.gridConfig = {
  rowClass: (row) => (row.status === 'inactive' ? 'row-inactive' : ''),
};

Then define the CSS class in your stylesheet:

.row-inactive { opacity: 0.5; }

Cell Styling

Style individual cells based on their value using cellClass on a column:

grid.columns = [
  {
    field: 'score',
    cellClass: (value) => {
      if (value >= 90) return 'cell-success';
      if (value < 50) return 'cell-danger';
      return '';
    },
  },
];

Tip

You can combine rowClass and cellClass. When styles conflict, cell styles win because cells are children of rows in the DOM hierarchy.

Use rowClass and cellClass to apply conditional styles based on data.

Show source

Renderers

Full control over cell content — Renderers let you create custom HTML elements for cells.

While formatters return plain text, renderers return DOM elements. Use renderers when you need:

• Custom components: Checkboxes, badges, progress bars, buttons
• Interactive elements: Links, icons, action buttons
• Rich formatting: Multiple elements, images, complex layouts

TypeScript

grid.columns = [
  {
    field: 'status',
    header: 'Status',
    renderer: (ctx) => {
      const badge = document.createElement('span');
      badge.className = `badge badge-${ctx.value}`;
      badge.textContent = ctx.value;
      return badge;
    },
  },
  {
    field: 'active',
    header: 'Active',
    renderer: (ctx) => {
      const checkbox = document.createElement('input');
      checkbox.type = 'checkbox';
      checkbox.checked = !!ctx.value;
      checkbox.disabled = true;
      return checkbox;
    },
  },
];

React

import { DataGrid, GridColumn } from '@toolbox-web/grid-react';

function EmployeeGrid({ rows }) {
  return (
    <DataGrid rows={rows}>
      <GridColumn
        field="status"
        header="Status"
        renderer={({ value }) => (
          <span className={`badge badge-${value}`}>{value}</span>
        )}
      />
      <GridColumn
        field="active"
        header="Active"
        renderer={({ value }) => (
          <input type="checkbox" checked={!!value} disabled />
        )}
      />
    </DataGrid>
  );
}

Vue

<script setup lang="ts">
import { TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';
</script>

<template>
  <TbwGrid :rows="rows">
    <TbwGridColumn field="status" header="Status">
      <template #cell="{ value }">
        <span :class="`badge badge-${value}`">{{ value }}</span>
      </template>
    </TbwGridColumn>
    <TbwGridColumn field="active" header="Active">
      <template #cell="{ value }">
        <input type="checkbox" :checked="!!value" disabled />
      </template>
    </TbwGridColumn>
  </TbwGrid>
</template>

Angular

import { Component } from '@angular/core';
import { Grid, TbwRenderer } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, TbwRenderer],
  template: `
    <tbw-grid [rows]="rows" style="height: 400px; display: block">
      <tbw-grid-column field="status" header="Status">
        <span *tbwRenderer="let value" [class]="'badge badge-' + value">
          {{ value }}
        </span>
      </tbw-grid-column>
      <tbw-grid-column field="active" header="Active">
        <input *tbwRenderer="let value" type="checkbox" [checked]="!!value" disabled />
      </tbw-grid-column>
    </tbw-grid>
  `,
})
export class EmployeeGridComponent {
  rows = [/* ... */];
}

The renderer receives a CellRenderContext — the cell value, the row object, the field name, and the column config.

Why no rowIndex?

Renderer and editor contexts intentionally provide the row object instead of a row index. A rowIndex reflects the row’s position in the grid’s current sorted/filtered/grouped view — it silently becomes stale whenever the user sorts, filters, or reorders. The row object is a stable identity that remains valid regardless of view state.

If you need the visual index at a specific moment (e.g. for conditional styling of even/odd rows), derive it inside the renderer:

renderer: (ctx) => {
  const rowIndex = grid.rows.indexOf(ctx.row);
  // Use rowIndex for one-time positional logic
}

For event-driven use cases, click and activation events (cell-click, row-click, cell-activate) already include rowIndex in their detail payload.

Renderers give full control over cell content — create badges, checkboxes, progress bars, and more.

Show source

Choosing: Formatter vs Renderer

Now that you’ve seen both, here’s a quick reference for picking the right one:

	Formatter (format)	Renderer (renderer)
Returns	String	DOM element
Use for	Currency, dates, percentages, text formatting	Checkboxes, badges, buttons, links, images
Performance	Faster (text only)	Slower (DOM creation)
Interactivity	None (display only)	Full (event listeners, components)

Rule of thumb: If you only need to change how a value looks, use a format function. If you need interactive elements or custom HTML structure, use a renderer.

Row Animation

The grid provides a built-in row animation API for highlighting changes, insertions, and removals with visual feedback.

Method	Description	CSS Variable
animateRow(i, 'change')	Flash highlight for data changes	--tbw-row-change-duration (500ms)
insertRow(i, row)	Slide-in animation for new rows	--tbw-row-insert-duration (300ms)
removeRow(i)	Fade-out animation for removed rows	--tbw-row-remove-duration (200ms)
applyTransaction(tx)	Animates add/update/remove in one pass	All of the above

// Highlight a row after updating
grid.rows[5].status = 'updated';
grid.animateRow(5, 'change');

// Animate by row ID (stable when sorted/filtered)
grid.animateRowById(data.id, 'change');

// Animate multiple rows at once
grid.animateRows([0, 2, 5], 'change');

Customize appearance:

tbw-grid {
  --tbw-row-change-duration: 750ms;
  --tbw-row-change-color: rgba(34, 197, 94, 0.25);
}

Built-in row animation API for highlighting changes, insertions, and removals.

Flash Change Insert Row Remove Last

Show source

Note

When using the EditingPlugin, rows are automatically animated with 'change' after a successful edit commit.

Type-Level Defaults

Define default formatters and renderers for all columns of a specific type:

TypeScript

grid.gridConfig = {
  typeDefaults: {
    currency: {
      format: (value) =>
        new Intl.NumberFormat('en-US', {
          style: 'currency',
          currency: 'USD',
        }).format(value),
    },
    boolean: {
      renderer: (ctx) => {
        const cb = document.createElement('input');
        cb.type = 'checkbox';
        cb.checked = !!ctx.value;
        cb.disabled = true;
        return cb;
      },
    },
    status: {
      renderer: (ctx) => {
        const badge = document.createElement('span');
        badge.className = `status-badge status-${ctx.value}`;
        badge.textContent = ctx.value;
        return badge;
      },
    },
  },
  columns: [
    { field: 'salary', type: 'currency' },
    { field: 'active', type: 'boolean' },
    { field: 'status', type: 'status' },
  ],
};

React

import { GridTypeProvider, DataGrid, GridColumn } from '@toolbox-web/grid-react';
import type { TypeDefaultsMap } from '@toolbox-web/grid-react';

const typeDefaults: TypeDefaultsMap = {
  currency: {
    format: (value) =>
      new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value),
  },
  boolean: {
    renderer: ({ value }) => <input type="checkbox" checked={!!value} disabled />,
  },
  status: {
    renderer: ({ value }) => (
      <span className={`status-badge status-${value}`}>{value}</span>
    ),
  },
};

function App() {
  return (
    <GridTypeProvider defaults={typeDefaults}>
      <DataGrid rows={rows}>
        <GridColumn field="salary" type="currency" />
        <GridColumn field="active" type="boolean" />
        <GridColumn field="status" type="status" />
      </DataGrid>
    </GridTypeProvider>
  );
}

Vue

<script setup lang="ts">
import { h } from 'vue';
import { GridTypeProvider, TbwGrid, TbwGridColumn } from '@toolbox-web/grid-vue';
import CheckboxCell from './CheckboxCell.vue';
import StatusBadge from './StatusBadge.vue';

const typeDefaults = {
  currency: {
    format: (value) =>
      new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value),
  },
  boolean: {
    renderer: ({ value }) => h(CheckboxCell, { checked: !!value }),
  },
  status: {
    renderer: ({ value }) => h(StatusBadge, { status: value }),
  },
};
</script>

<template>
  <GridTypeProvider :defaults="typeDefaults">
    <TbwGrid :rows="rows">
      <TbwGridColumn field="salary" type="currency" />
      <TbwGridColumn field="active" type="boolean" />
      <TbwGridColumn field="status" type="status" />
    </TbwGrid>
  </GridTypeProvider>
</template>

Angular

import { Component } from '@angular/core';
import { Grid, provideGridTypeDefaults } from '@toolbox-web/grid-angular';
import { CheckboxCellComponent } from './checkbox-cell.component';
import { StatusBadgeComponent } from './status-badge.component';

@Component({
  imports: [Grid],
  providers: [
    provideGridTypeDefaults({
      currency: {
        format: (value) =>
          new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value),
      },
      boolean: { renderer: CheckboxCellComponent },
      status: { renderer: StatusBadgeComponent },
    }),
  ],
  template: `
    <tbw-grid [rows]="rows" [columns]="columns" />
  `,
})
export class AppComponent {
  columns = [
    { field: 'salary', type: 'currency' },
    { field: 'active', type: 'boolean' },
    { field: 'status', type: 'status' },
  ];
}

Type defaults reduce repetition when many columns share the same presentation. Column-level format or renderer overrides type defaults when both are specified.

Custom Header Renderers

Customize column header cells using headerLabelRenderer or headerRenderer.

Tip

The framework adapters (React, Vue, Angular) bridge headerRenderer and headerLabelRenderer — you can use React JSX, Vue components/render functions, or Angular component classes just like cell renderers. Vanilla DOM functions also work.

headerLabelRenderer — Modify just the label portion of the header (sort icons and filter buttons are still managed by the grid):

TypeScript

{
  field: 'name',
  header: 'Name',
  headerLabelRenderer: ({ value }) => {
    const span = document.createElement('span');
    span.innerHTML = `${value} <span style="color:red">*</span>`;
    return span;
  },
}

React

// In GridConfig or ColumnConfig
{
  field: 'name',
  header: 'Name',
  headerLabelRenderer: ({ value }) => (
    <span>{value} <span style={{ color: 'red' }}>*</span></span>
  ),
}

Vue

// In GridConfig or ColumnConfig
{
  field: 'name',
  header: 'Name',
  headerLabelRenderer: ({ value }) =>
    h('span', [value, h('span', { style: 'color:red' }, ' *')]),
}

Angular

// Using a component class in ColumnConfig
{
  field: 'name',
  header: 'Name',
  headerLabelRenderer: RequiredLabelComponent,
}

// RequiredLabelComponent
@Component({
  selector: 'app-required-label',
  template: `{{ value() }} <span style="color:red">*</span>`,
})
export class RequiredLabelComponent {
  value = input<string>();
  column = input<unknown>();
}

headerRenderer — Full control over the entire header cell. You are responsible for rendering sort icons using ctx.renderSortIcon():

TypeScript

{
  field: 'email',
  header: 'Email',
  headerRenderer: (ctx) => {
    const wrapper = document.createElement('div');
    wrapper.style.cssText = 'display:flex;align-items:center;gap:6px;width:100%';

    const icon = document.createElement('span');
    icon.textContent = '📧';
    wrapper.appendChild(icon);

    const label = document.createElement('span');
    label.textContent = ctx.value;
    label.style.flex = '1';
    wrapper.appendChild(label);

    const sortIcon = ctx.renderSortIcon();
    if (sortIcon) wrapper.appendChild(sortIcon);
    return wrapper;
  },
}

React

// In GridConfig or ColumnConfig
// Use ctx.sortState to render your own sort indicator in JSX
{
  field: 'email',
  header: 'Email',
  headerRenderer: (ctx) => (
    <div style={{ display: 'flex', alignItems: 'center', gap: '6px', width: '100%' }}>
      <span>📧</span>
      <span style={{ flex: 1 }}>{ctx.value}</span>
      {ctx.sortState && (
        <span className="sort-icon">
          {ctx.sortState === 'asc' ? '▲' : '▼'}
        </span>
      )}
    </div>
  ),
}

Vue

// In GridConfig or ColumnConfig
// Use ctx.sortState to render your own sort indicator
{
  field: 'email',
  header: 'Email',
  headerRenderer: (ctx) =>
    h('div', { style: 'display:flex;align-items:center;gap:6px;width:100%' }, [
      h('span', '📧'),
      h('span', { style: 'flex:1' }, ctx.value),
      ctx.sortState
        ? h('span', { class: 'sort-icon' },
            ctx.sortState === 'asc' ? '▲' : '▼')
        : null,
    ]),
}

Angular

// Using a component class in ColumnConfig
{
  field: 'email',
  header: 'Email',
  headerRenderer: EmailHeaderComponent,
}

// EmailHeaderComponent
@Component({
  selector: 'app-email-header',
  template: `
    <div style="display:flex;align-items:center;gap:6px;width:100%">
      <span>📧</span>
      <span style="flex:1">{{ value() }}</span>
    </div>
  `,
})
export class EmailHeaderComponent {
  value = input<string>();
  column = input<unknown>();
  sortState = input<'asc' | 'desc' | null>();
  filterActive = input<boolean>();
  renderSortIcon = input<() => HTMLElement | null>();
  renderFilterButton = input<() => HTMLElement | null>();
}

The HeaderCellContext gives you the label text, the column config, the current sort/filter state, and helpers to render the built-in sort icon and filter button when you want to keep them.

Name uses headerLabelRenderer (adds a red asterisk). Email uses headerRenderer (full control with custom icon + sort icon).

Show source

---

Column State Persistence

The grid tracks column state — widths, sort direction, order, and visibility. You can save, load, and reset this state for user personalization.

What State Contains

getColumnState() returns an array of GridColumnState objects — one entry per column capturing its field, current width, sort direction and priority, and visibility.

Listening for Changes

The column-state-change event fires whenever the user resizes, reorders, sorts, or hides/shows columns:

TypeScript

grid.on('column-state-change', (state) => {
  localStorage.setItem('my-grid-state', JSON.stringify(state));
});

React

<DataGrid
  rows={rows}
  onColumnStateChange={(e) => {
    localStorage.setItem('my-grid-state', JSON.stringify(e.detail));
  }}
/>

Vue

<template>
  <TbwGrid :rows="rows" @column-state-change="onColumnStateChange" />
</template>

<script setup lang="ts">
function onColumnStateChange(e: CustomEvent<GridColumnState[]>) {
  localStorage.setItem('my-grid-state', JSON.stringify(e.detail));
}
</script>

Angular

<tbw-grid [rows]="rows" (column-state-change)="onColumnStateChange($event)" />

onColumnStateChange(e: CustomEvent<GridColumnState[]>) {
  localStorage.setItem('my-grid-state', JSON.stringify(e.detail));
}

Applying Saved State

Restore a previously saved state using applyColumnState():

const saved = localStorage.getItem('my-grid-state');
if (saved) {
  grid.applyColumnState(JSON.parse(saved));
}

Resetting State

Re-assign the original column definitions to reset to defaults:

grid.columns = [...originalColumns];

💾 Save State 📂 Load State 🗑️ Clear Saved ↩️ Reset Grid

Show source

---

Shell Components

The shell wraps the grid with an optional header bar (title + toolbar) and a collapsible tool panel sidebar.

Basic Shell

Enable the shell by providing a shell.header.title. Features like visibility automatically register a tool panel when the shell is active.

import '@toolbox-web/grid/features/visibility';

grid.gridConfig = {
  shell: { header: { title: 'Employee Data' } },
  features: { visibility: true },
};

HEADER

Show title Show title in shell header

Show header content Show custom header content (row count)

Show toolbar button Show custom toolbar button

PLUGINS

Visibility plugin Include VisibilityPlugin (column chooser)

PANELS

Custom tool panel Show custom tool panel via API

Panel position Tool panel position

left right

Show source

Light DOM Configuration

Configure the shell declaratively using <tbw-grid-header> and <tbw-grid-header-content> elements:

<tbw-grid>
  <tbw-grid-header title="Employee Directory">
    <tbw-grid-header-content>
      <span id="row-count">0 employees</span>
    </tbw-grid-header-content>
  </tbw-grid-header>
</tbw-grid>

Shell configured via <tbw-grid-header> light DOM elements — no JavaScript shell config needed.

20 employees

Show source

Multiple Tool Panels

Register multiple tool panels — each gets a tab in the sidebar. Panels can be registered via configuration or the runtime registerToolPanel() API.

TypeScript

grid.registerToolPanel({
  id: 'filter-panel',
  title: 'Filters',
  icon: '🔍',
  render(container) {
    container.innerHTML = '<p>Filter controls here</p>';
  },
});

React

import { DataGrid, GridToolPanel } from '@toolbox-web/grid-react';

function MyGrid({ rows }) {
  return (
    <DataGrid rows={rows} gridConfig={config}>
      <GridToolPanel id="filter-panel" title="Filters" icon="🔍">
        {({ grid }) => <p>Filter controls here</p>}
      </GridToolPanel>
    </DataGrid>
  );
}

Vue

<script setup lang="ts">
import { TbwGrid, TbwGridToolPanel } from '@toolbox-web/grid-vue';
</script>

<template>
  <TbwGrid :rows="rows" :grid-config="config">
    <TbwGridToolPanel id="filter-panel" label="Filters" icon="🔍">
      <template #default="{ grid }">
        <p>Filter controls here</p>
      </template>
    </TbwGridToolPanel>
  </TbwGrid>
</template>

Angular

<tbw-grid [rows]="rows" [gridConfig]="config">
  <tbw-grid-tool-panel id="filter-panel" title="Filters" icon="🔍">
    <ng-template>
      <p>Filter controls here</p>
    </ng-template>
  </tbw-grid-tool-panel>
</tbw-grid>

Multiple tool panels (Columns, Filter, Settings). Click toolbar icons to toggle each.

Show source

Toolbar Buttons

Add custom buttons to the shell toolbar using framework wrapper components or the registerToolbarContent() API:

TypeScript

<tbw-grid>
  <tbw-grid-tool-buttons>
    <button onclick="exportData()">📥 Export</button>
    <button onclick="printGrid()">🖨️ Print</button>
  </tbw-grid-tool-buttons>
</tbw-grid>

React

import { DataGrid, GridToolButtons } from '@toolbox-web/grid-react';

function MyGrid({ rows }) {
  return (
    <DataGrid rows={rows} gridConfig={config}>
      <GridToolButtons>
        <button onClick={exportData}>📥 Export</button>
        <button onClick={printGrid}>🖨️ Print</button>
      </GridToolButtons>
    </DataGrid>
  );
}

Vue

<script setup lang="ts">
import { TbwGrid, TbwGridToolButtons } from '@toolbox-web/grid-vue';
</script>

<template>
  <TbwGrid :rows="rows" :grid-config="config">
    <TbwGridToolButtons>
      <button @click="exportData">📥 Export</button>
      <button @click="printGrid">🖨️ Print</button>
    </TbwGridToolButtons>
  </TbwGrid>
</template>

Angular

<tbw-grid [rows]="rows" [gridConfig]="config">
  <tbw-grid-tool-buttons>
    <button (click)="exportData()">📥 Export</button>
    <button (click)="printGrid()">🖨️ Print</button>
  </tbw-grid-tool-buttons>
</tbw-grid>

Custom toolbar buttons via light DOM. The grid provides the container — you provide the HTML.

📥 🖨️

Show source

Shell Configuration Reference:

Option	Type	Default	Description
shell.header.title	string	—	Title text in the header bar
shell.toolPanel.position	'left' | 'right'	'right'	Sidebar position
shell.toolPanel.width	number	280	Sidebar width in pixels
shell.toolPanel.defaultOpen	string	—	Panel ID to open on load
shell.toolPanel.persistState	boolean	false	Remember open/closed state
shell.toolPanel.closeOnClickOutside	boolean	false	Close on outside click

---

Loading States

The grid supports loading indicators at three levels: grid-wide, per-row, and per-cell.

API Reference

Grid-level — Shows a full overlay spinner:

grid.loading = true;
// ... fetch data ...
grid.loading = false;

The loading attribute also works in HTML: <tbw-grid loading></tbw-grid>.

Row-level — Shows a spinner on a specific row (requires getRowId):

grid.setRowLoading('row-42', true);
// ... update row ...
grid.setRowLoading('row-42', false);

Cell-level — Shows a spinner on a specific cell:

grid.setCellLoading('row-42', 'status', true);
// ... update cell ...
grid.setCellLoading('row-42', 'status', false);

Query and clear:

grid.isRowLoading('row-42');          // boolean
grid.isCellLoading('row-42', 'name'); // boolean
grid.clearAllLoading();               // remove all indicators

Mode

grid row cell

Auto-reset (1 s)

▶ Simulate

Click ▶ Simulate to show the grid loading overlay.

Show source

Custom Loading Renderer

Replace the default spinner with a custom element using loadingRenderer:

TypeScript

grid.gridConfig = {
  loadingRenderer: (context) => {
    const el = document.createElement('div');
    el.className = 'my-spinner';
    // context.size is 'large' (grid-level) or 'small' (row/cell)
    el.style.width = context.size === 'large' ? '48px' : '16px';
    el.style.height = el.style.width;
    return el;
  },
};

React

import { DataGrid } from '@toolbox-web/grid-react';
import type { GridConfig } from '@toolbox-web/grid-react';

const config: GridConfig = {
  loadingRenderer: ({ size }) => (
    <div
      className="my-spinner"
      style={{
        width: size === 'large' ? '48px' : '16px',
        height: size === 'large' ? '48px' : '16px',
      }}
    />
  ),
};

function MyGrid({ rows }) {
  return <DataGrid rows={rows} gridConfig={config} />;
}

Vue

<script setup lang="ts">
import { h } from 'vue';
import { TbwGrid } from '@toolbox-web/grid-vue';
import type { GridConfig } from '@toolbox-web/grid-vue';

// Option 1: Render function
const config: GridConfig = {
  loadingRenderer: ({ size }) =>
    h('div', {
      class: 'my-spinner',
      style: {
        width: size === 'large' ? '48px' : '16px',
        height: size === 'large' ? '48px' : '16px',
      },
    }),
};

// Option 2: Vue component (receives `size` prop)
// import MySpinner from './MySpinner.vue';
// const config: GridConfig = { loadingRenderer: MySpinner };
</script>

<template>
  <TbwGrid :rows="rows" :grid-config="config" />
</template>

Angular

import { Component, input } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { GridConfig } from '@toolbox-web/grid-angular';

// Loading spinner component (receives `size` input)
@Component({
  selector: 'app-spinner',
  template: `
    <div class="my-spinner"
      [style.width]="size() === 'large' ? '48px' : '16px'"
      [style.height]="size() === 'large' ? '48px' : '16px'">
    </div>
  `,
})
export class SpinnerComponent {
  size = input<'large' | 'small'>('large');
}

@Component({
  imports: [Grid],
  template: `<tbw-grid [rows]="rows" [gridConfig]="config" />`,
})
export class MyGridComponent {
  config: GridConfig = {
    loadingRenderer: SpinnerComponent,
  };
}

The LoadingContext provides a size property: 'large' for the grid-wide overlay (up to 48×48 px) and 'small' for row/cell indicators (sized to the row height).

Replace the default spinner with a custom linear progress bar. Click Toggle to switch loading state.

Toggle Loading

Show source

---

Variable Row Heights

By default all rows share a fixed height (--tbw-row-height, default 28 px). You can configure per-row heights using a function.

Configuration

// Fixed height for all rows
grid.gridConfig = { rowHeight: 56 };

// Per-row height function
grid.gridConfig = {
  rowHeight: (row, index) => (row.hasDetails ? 80 : 40),
};

If your function returns undefined for a row, the grid auto-measures that row’s actual DOM height after rendering.

How Auto-Measurement Works

1. The grid renders rows with an estimated height.
2. After paint, it reads offsetHeight for each rendered row.
3. Measured heights are cached and the position cache is rebuilt.
4. A ResizeObserver watches for late layout shifts (font loading, lazy images) and re-measures automatically.

Row Identity for Height Caching

Measured heights are cached using:

• getRowId / rowId — preferred, survives sort/filter changes
• Object reference (WeakMap) — fallback when no ID is configured

Provide getRowId for best results when rows are re-sorted, filtered, or grouped.

Plugin-Provided Heights

Plugins can override row heights by implementing the getRowHeight(row, index) hook. The MasterDetailPlugin and ResponsivePlugin use this to provide expanded-row heights.

Performance Considerations

• Fixed heights are fastest — the grid can calculate positions with pure math.
• Function-based heights add a per-row function call during position-cache rebuilds.
• Auto-measured heights require a DOM read pass after rendering — avoid for 10 k+ row grids unless combined with getRowId caching.
• When mixing fixed and auto-measured rows, return a number for most rows and undefined only for rows that need measurement.

Show source

---

Events

The grid dispatches standard CustomEvents for user interactions — clicks, sort changes, column resizes, and more. Plugin-specific events (selection, editing, filtering, etc.) are also available when those plugins are active.

For the complete event reference — including listening patterns per framework, cancelable events, and all plugin events — see the Events section of the API Reference.

---

Methods

The <tbw-grid> element exposes public methods for programmatic control — data manipulation, focus management, column state persistence, custom styles, shell control, loading indicators, row animation, and more. Use createGrid() or queryGrid() for type-safe access.

For the complete method reference — including signatures, return types, and factory functions — see the API Reference page.

---

See Also

• Getting Started — Installation and setup
• Common Patterns — Full application recipes
• Plugins — Extend with selection, filtering, editing, and more
• Theming — CSS custom properties, dark mode, themes
• Architecture — Render scheduler, Light DOM, design decisions
• Plugin System — Build your own plugins