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:

Vanilla JS

<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). Here’s a summary of the most common options:

Property	Type	Description
columns	ColumnConfig[]	Column definitions
rows	any[]	Row data array
fitMode	'stretch' | 'fixed'	How columns fill available width
sortable	boolean	Enable sorting on all columns
resizable	boolean	Enable resizing on all columns
rowHeight	number | Function	Fixed or variable row heights
plugins	BaseGridPlugin[]	Plugin instances
rowClass	Function	Dynamic row CSS classes
typeDefaults	Record<string, …>	Default format/renderer per column type
shell	ShellConfig	Shell layout (header, tool panels)
loadingRenderer	LoadingRenderer	Custom loading indicator
getRowId	(row) => string	Unique row identity function

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

Choosing: Formatter vs Renderer

The grid offers two ways to customize how cell data is displayed:

	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.

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

Vanilla JS

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, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import { Grid, TbwRenderer } from '@toolbox-web/grid-angular';

@Component({
  imports: [Grid, TbwRenderer],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  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 with value, row, column, and field. See the CellRenderContext API for details.

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

Show source

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)

// 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:

Vanilla JS

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, CUSTOM_ELEMENTS_SCHEMA } 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],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  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):

Vanilla JS

{
  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():

Vanilla JS

{
  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 provides:

Property / Method	Description
value	The header label text
column	Full ColumnConfig object
sortState	Current sort direction: 'asc', 'desc', or null — use for custom JSX sort indicators
filterActive	Whether this column has an active filter
renderSortIcon()	Returns the built-in sort indicator DOM element (or null)
renderFilterButton()	Returns the filter button element (when FilteringPlugin is active)

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, each containing:

Property	Type	Description
field	string	Column field identifier
width	number	Current pixel width
sort	'asc' | 'desc' | null	Sort direction
sortIndex	number | null	Multi-sort priority
hidden	boolean	Visibility state

Listening for Changes

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

Vanilla JS

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.

Vanilla JS

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:

Vanilla JS

<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:

Vanilla JS

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, CUSTOM_ELEMENTS_SCHEMA } 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],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  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.

---

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