DataGrid

A virtualized data table for large data sets (500 rows to millions). Sibling component of <Table> — shares the same column model, sort/search/filter/selection logic, cell renderer library, RBAC integration, and visual identity. The difference is the render strategy: DataGrid mounts only the window of visible rows in DOM, making it performant even with 100k+ rows.

import { DataGrid } from '@dashforge/tw';

<DataGrid
  rows={users}
  cols={[
    { field: 'name',  header: 'Name',  sortable: true, searchable: true },
    { field: 'email', header: 'Email', searchable: true },
    { field: 'age',   header: 'Age',   sortable: true },
  ]}
  getRowId={(row) => row.id}
  rowHeight={48}
  height="600px"
/>

When to use DataGrid vs Table

Both components ship the same visual identity (Stripe-style clean lines, hover row actions, sticky header, smart defaults, canonical theme patterns). They differ at the runtime characteristics level. Pick based on data size + features needed, not appearance.

Use <Table> when

• Your data set is < ~500 rows in the typical page
• Cell content has variable height (long text, embedded images, nested forms)
• You need expandable rows for inline detail views
• You want the simplest possible API surface

Use <DataGrid> when

• Your data set is 500+ rows (or unbounded — millions)
• Scroll performance matters more than expandable rows
• You need server-side sort / filter / search / pagination — DataGrid emits the change events but doesn't run the operations locally
• You need sticky left or right columns (pinned IDs / names or trailing action menus during horizontal scroll)
• You want per-column filter UI chips (text contains / number range / date range / boolean) auto-detected by column type
• You want user-driven column controls — visibility dialog, resize via drag, reorder via drag — without writing a Settings page
• You want fine-grained control over select-all semantics ('visible' window vs 'allLoaded' full dataset)

"Switch later" path

Both components share the same column model (TableColumn<T>), same cell renderer library (RenderText, RenderTwoLine, RenderChip, RenderButton, RowActionsMenu), and same i18n surface (labels). Migrating from Table to DataGrid (when you outgrow the row count) is mechanical:

- <Table
+ <DataGrid
    rows={users}
    cols={columns}
    getRowId={(row) => row.id}
+   rowHeight={48}
+   height="600px"
  />

The new required props are rowHeight + height. Everything else keeps working. Expandable rows are the one feature you lose in the swap — Table-specific until v1-bis.

Quick start

Minimal

<DataGrid
  rows={users}              // T[]
  cols={columns}            // TableColumn<T>[]
  getRowId={(r) => r.id}    // required for stable keys
  rowHeight={48}            // required for windowing math
  height="600px"            // required for container bounding
/>

Both rowHeight and height are required for the virtualization to compute the visible window. The height is a CSS length — pass "600px", "60vh", or set via sx / parent layout.

import { DataGrid, type TableColumn } from '@dashforge/tw';

interface User {
  id: string;
  name: string;
  email: string;
  age: number;
  city: string;
}

const CITIES = ['Roma', 'Milano', 'Berlin', 'London', 'Paris'];

// 200 rows — well above where Table starts to feel sluggish, but
// virtualization keeps only ~6 rows mounted in DOM at any time.
const USERS: User[] = Array.from({ length: 200 }).map((_, i) => ({
  id: `u${i}`,
  name: `User ${i + 1}`,
  email: `user${i + 1}@example.com`,
  age: 22 + (i % 50),
  city: CITIES[i % CITIES.length] as string,
}));

const COLS: TableColumn<User>[] = [
  { field: 'name',  header: 'Name',  sortable: true },
  { field: 'email', header: 'Email' },
  { field: 'age',   header: 'Age',   sortable: true },
  { field: 'city',  header: 'City' },
];

<DataGrid
  rows={USERS}
  cols={COLS}
  getRowId={(row) => row.id}
  rowHeight={40}
  height="280px"
  sx="w-full max-w-2xl"
/>

Smart defaults (same as Table)

Auto-detected from the first non-null value across visible rows:

Font family is the consumer's choice — tabular-nums is a font-feature setting that preserves the consumer theme font-sans. monospace: true is the explicit opt-in for font-mono.

Virtualization

DataGrid uses homemade virtualization (no @tanstack/react-virtual, no react-window — zero new runtime deps). The hook (useVirtualizer in _shared/data/) uses:

• scroll event listener on the bounded container
• requestAnimationFrame debounce so scroll updates never exceed one re-render per paint frame
• ResizeObserver to re-virtualize when the container size changes (window resize, sidebar toggle, etc.)
• Spacer <tr> approach: a <tr aria-hidden="true"> with inline height renders ABOVE and BELOW the visible row window, preserving the scrollbar size + <table> semantics

Window math:

visibleStart  = floor(scrollTop / rowHeight) - overscan
visibleEnd    = ceil((scrollTop + viewportHeight) / rowHeight) + overscan
paddingTop    = visibleStart * rowHeight
paddingBottom = (totalCount - 1 - visibleEnd) * rowHeight

Configuration:

Performance characteristics

For a 10 000-row data set with rowHeight={48} and height="600px":

• DOM nodes: ~18 <tr> (13 visible + 5 overscan) + 2 spacer rows
• Mount time: ~12-18 ms
• Scroll throttling: bounded to 60 fps via requestAnimationFrame
• Memory: bounded by the visible window, not the dataset size

Server-side mode

Each pipeline step has an independent opt-in flag. With the flag on, DataGrid emits the change event but does NOT run the operation locally — the consumer is expected to provide the resulting rows array.

<DataGrid
  rows={pageOfRows}                  // The slice the server returned
  cols={columns}
  getRowId={(r) => r.id}
  rowHeight={48}
  height="600px"

  // Sort emits but doesn't run locally — server returns pre-sorted rows
  serverSideSort
  sortModel={sortModel}
  onSortChange={setSortModel}       // → triggers a fetch

  // Filter same shape
  serverSideFilter
  filterModel={filterModel}
  onFilterChange={setFilterModel}

  // Search same shape (debounced before emit, default 200ms)
  serverSideSearch
  searchQuery={query}
  onSearchQueryChange={setQuery}    // → triggers a fetch

  // Virtual scroll height comes from totalCount, NOT rows.length
  serverSidePagination
  totalCount={1_000_000}            // required when serverSidePagination
/>

Mix and match. Each flag is independent. Use serverSideSort alone if your filter happens locally but sort hits the backend. Use serverSidePagination + totalCount to render a virtual scrollbar for a dataset whose rows you fetch page-by-page from a server.

import { useState } from 'react';
import {
  DataGrid,
  type TableColumn,
  type TableSortModel,
  type TableFilterModel,
} from '@dashforge/tw';

interface Row {
  id: string;
  name: string;
  email: string;
  status: 'active' | 'pending';
}

// Pretend this is a server-returned page slice. The consumer fetches
// it (via React Query / SWR / RTK Query) based on the emitted
// sort/filter/search/page events.
const PAGE: Row[] = Array.from({ length: 25 }).map((_, i) => ({
  id: `r${i}`,
  name: `User ${i + 1}`,
  email: `user${i + 1}@example.com`,
  status: i % 3 === 0 ? 'pending' : 'active',
}));

const COLS: TableColumn<Row>[] = [
  { field: 'name',   header: 'Name',   sortable: true, searchable: true },
  { field: 'email',  header: 'Email',  searchable: true },
  { field: 'status', header: 'Status', filterable: true },
];

function MyGrid() {
  const [sortModel, setSortModel] = useState<TableSortModel>([]);
  const [filterModel, setFilterModel] = useState<TableFilterModel>([]);
  const [query, setQuery] = useState('');

  return (
    <DataGrid
      rows={PAGE}
      cols={COLS}
      getRowId={(row) => row.id}
      rowHeight={40}
      height="280px"
      enableSearch
      serverSideSearch
      searchQuery={query}
      onSearchQueryChange={setQuery}
      serverSideSort
      sortModel={sortModel}
      onSortChange={setSortModel}
      serverSideFilter
      filterModel={filterModel}
      onFilterChange={setFilterModel}
      serverSidePagination
      totalCount={120}
      sx="w-full max-w-2xl"
    />
  );
}

Sticky columns (left + right)

CSS-only — uses position: sticky; left: 0 (or right: 0) with a z-index ladder that handles the corner intersection with the sticky header:

z-index ladder:
  thead (z-10)
    < stickyLeftCell  / stickyRightCell  in body (z-[1])
    < stickyLeftHeaderCell / stickyRightHeaderCell (z-20)  ← corners highest

Apply via the column definition:

const cols: TableColumn<User>[] = [
  {
    field: 'name',
    header: 'Name',
    sticky: 'left',          // pinned during horizontal scroll
    width: 220,              // fixed width is recommended for sticky
    sortable: true,
  },
  // …middle columns scroll horizontally underneath
  {
    field: 'actions',
    header: 'Actions',
    sticky: 'right',         // pinned on the trailing edge (0.8.0-beta)
    width: 110,
    cellRenderer: ({ row }) => <RowActionsMenu row={row} actions={…} />,
  },
];

Multiple sticky: 'left' columns stack left-to-right; multiple sticky: 'right' columns stack right-to-left. Right-sticky cells get a border-l automatically so they read as a separate "pinned" region against the scrollable middle.

import { DataGrid, RowActionsMenu, type TableColumn } from '@dashforge/tw';

interface Row {
  id: string;
  name: string;
  email: string;
  city: string;
  country: string;
  salary: number;
  joined: string;
}

const ROWS: Row[] = Array.from({ length: 100 }).map((_, i) => ({
  id: `r${i}`,
  name: `User ${i + 1}`,
  email: `user${i + 1}@example.com`,
  city: ['Roma', 'Milano', 'Berlin', 'London'][i % 4] as string,
  country: ['IT', 'IT', 'DE', 'GB'][i % 4] as string,
  salary: 30_000 + (i % 60) * 1_500,
  joined: `2024-${String((i % 12) + 1).padStart(2, '0')}-15`,
}));

const COLS: TableColumn<Row>[] = [
  { field: 'name',    header: 'Name',         sticky: 'left',  width: 180, sortable: true },
  { field: 'email',   header: 'Email',        width: 220 },
  { field: 'city',    header: 'City',         width: 140 },
  { field: 'country', header: 'Country',      width: 100 },
  { field: 'salary',  header: 'Salary (USD)', width: 140, sortable: true,
    cellRenderer: ({ value }) => `${(value as number).toLocaleString('en-US')}` },
  { field: 'joined',  header: 'Joined',       width: 130, sortable: true },
];

<DataGrid
  rows={ROWS}
  cols={[
    ...COLS,
    {
      field: 'id',
      header: 'Actions',
      sticky: 'right',
      width: 110,
      resizable: false,
      reorderable: false,
      hideable: false,
      cellRenderer: ({ row }) => (
        <RowActionsMenu
          row={row}
          actions={[
            { label: 'Edit',   onClick: (r) => console.log('edit', r.id) },
            { label: 'Delete', onClick: (r) => console.log('delete', r.id), color: 'danger' },
          ]}
        />
      ),
    },
  ]}
  getRowId={(row) => row.id}
  rowHeight={40}
  height="280px"
  sx="w-full max-w-xl"
/>

Per-column filter UI

Opt in per column with filterable: true (0.8.0-beta). A filter icon appears in the column header; clicking it opens a <Popover> with the right input for the column type, auto-detected via useColumnAutoDetect:

const cols: TableColumn<Order>[] = [
  { field: 'customer', header: 'Customer', filterable: true },
  // number → range filter
  { field: 'total',    header: 'Total',    filterable: true },
  // boolean → radios
  { field: 'paid',     header: 'Paid',     filterable: true },
  // ISO date string → date range
  { field: 'date',     header: 'Date',     filterable: true },
];

<DataGrid
  rows={orders}
  cols={cols}
  getRowId={(r) => r.id}
  rowHeight={48}
  height="600px"
  // Optionally lift the filter model for persistence / server-side mode:
  // filterModel={filterModel}
  // onFilterChange={setFilterModel}
/>

Override the autodetect with cols[i].filterType when the heuristic picks the wrong one — e.g. an ID column typed as number but you want a text-contains UI:

{ field: 'userId', header: 'User ID', filterable: true, filterType: 'text' }

Operator model: every filter commits to the same filterModel shape — { field, op, value }[] with op: 'contains' | 'equals' | 'between'. The between value is [min, max] where each end can be null for an open range. The filter icon highlights primary-700 (aria-pressed=true) when an active filter applies to that column.

i18n: all filter labels go through the labels prop — filterColumn / filterApply / filterClear / filterMin / filterMax / filterFrom / filterTo / filterAll / filterTrue / filterFalse.

import { DataGrid, type TableColumn } from '@dashforge/tw';

interface Order {
  id: string;
  customer: string;
  total: number;
  paid: boolean;
  date: string;
}

const ORDERS: Order[] = Array.from({ length: 80 }).map((_, i) => ({
  id: `o${i}`,
  customer: ['Acme Corp', 'Globex', 'Initech', 'Umbrella', 'Soylent'][i % 5] as string,
  total: 100 + (i % 50) * 37,
  paid: i % 3 !== 0,
  date: `2024-${String((i % 12) + 1).padStart(2, '0')}-${String((i % 28) + 1).padStart(2, '0')}`,
}));

// Each `filterable: true` column gets a filter icon in its header.
// Filter UI auto-adapts: number → range, boolean → radios,
// date string → date range, anything else → text contains.
const COLS: TableColumn<Order>[] = [
  { field: 'customer', header: 'Customer', sortable: true, filterable: true },
  { field: 'total',    header: 'Total',    sortable: true, filterable: true,
    cellRenderer: ({ value }) => `${(value as number).toLocaleString('en-US')}` },
  { field: 'paid',     header: 'Paid',     filterable: true },
  { field: 'date',     header: 'Date',     sortable: true, filterable: true },
];

<DataGrid
  rows={ORDERS}
  cols={COLS}
  getRowId={(row) => row.id}
  rowHeight={40}
  height="280px"
  sx="w-full max-w-2xl"
/>

User-driven column controls

Three independent opt-in flags, all defaulting true in 0.8.0-beta:

• enableColumnVisibility — adds a "Columns" button to the toolbar that opens a <Dialog> with one checkbox per column.
• enableColumnResize — hover the right edge of any <th>, cursor becomes col-resize, drag commits the new width.
• enableColumnReorder — drag any header onto another to reposition; a 2px primary-500 indicator marks the drop side (LEFT half = insert before, RIGHT half = insert after).

Per-column opt-outs map to new TableColumn<T> axes:

const cols: TableColumn<User>[] = [
  // hideable: false → not offered in the visibility dialog
  // (structurally required, e.g. an ID column)
  { field: 'name',   header: 'Name',  hideable: false },

  // defaultHidden: true → starts hidden, user re-shows via dialog
  { field: 'joined', header: 'Joined', defaultHidden: true },

  // resize bounds — minWidth/maxWidth clamp the drag
  { field: 'email',  header: 'Email', minWidth: 160, maxWidth: 320 },

  // structurally pinned — no resize, no reorder, no hide
  { field: 'actions', header: '',     sticky: 'right',
    resizable: false, reorderable: false, hideable: false },
];

All three states are controllable for persistence (LocalStorage, server-side prefs, URL):

<DataGrid
  rows={rows}
  cols={cols}
  getRowId={(r) => r.id}
  rowHeight={48}
  height="600px"

  hiddenColumns={hidden}        onHiddenColumnsChange={setHidden}
  columnWidths={widths}         onColumnWidthsChange={setWidths}
  columnOrder={order}           onColumnOrderChange={setOrder}
/>

Built on the existing <Dialog> (visibility), native pointer events (resize), and native HTML5 drag-and-drop (reorder) — zero new runtime deps.

import { DataGrid, type TableColumn } from '@dashforge/tw';

interface Row {
  id: string;
  name: string;
  email: string;
  role: string;
  team: string;
  joined: string;
}

const ROWS: Row[] = Array.from({ length: 60 }).map((_, i) => ({
  id: `r${i}`,
  name: `User ${i + 1}`,
  email: `user${i + 1}@example.com`,
  role: ['admin', 'editor', 'viewer'][i % 3] as string,
  team: ['Platform', 'Growth', 'Ops', 'Design'][i % 4] as string,
  joined: `2024-${String((i % 12) + 1).padStart(2, '0')}-15`,
}));

// Three user-driven controls — all default-on:
//   1. The toolbar "Columns" button opens the visibility dialog.
//   2. Hover the right edge of a <th> and drag to resize.
//   3. Drag any header onto another to reorder.
const COLS: TableColumn<Row>[] = [
  { field: 'name',   header: 'Name',   width: 180, hideable: false, sortable: true },
  { field: 'email',  header: 'Email',  width: 220, minWidth: 160, maxWidth: 320 },
  { field: 'role',   header: 'Role',   width: 110 },
  { field: 'team',   header: 'Team',   width: 130 },
  { field: 'joined', header: 'Joined', width: 130, defaultHidden: true, sortable: true },
];

<DataGrid
  rows={ROWS}
  cols={COLS}
  getRowId={(row) => row.id}
  rowHeight={40}
  height="280px"
  sx="w-full max-w-2xl"
/>

Selection at scale

Selecting "all" in a 10 000-row data grid has two reasonable semantics. The selectAllScope prop lets you pick:

<DataGrid
  rows={users}
  cols={cols}
  getRowId={(r) => r.id}
  rowHeight={48}
  height="600px"
  rowSelection="multiple"
  selectAllScope="visible"   // narrow scope — useful when total >> window
  selectedRowIds={selected}
  onSelectionChange={setSelected}
/>

For "select all in the server-side dataset" (e.g. select all 1M rows that match a filter), the consumer wires it themselves:

async function selectAllOnServer() {
  const ids = await fetch('/api/users/ids?filter=' + ...).then((r) => r.json());
  setSelected(ids);
}

Optional internal pagination

DataGrid + virtualization can scroll a million rows smoothly — but some UX patterns still want explicit "Page X of Y" navigation. Opt in via the pagination prop:

const [page, setPage] = useState(1);
const [pageSize, setPageSize] = useState(50);

<DataGrid
  rows={users}
  cols={cols}
  getRowId={(r) => r.id}
  rowHeight={48}
  height="600px"
  pagination={{
    page,
    pageSize,
    onPageChange: setPage,
    onPageSizeChange: setPageSize,
    pageSizeOptions: [20, 50, 100, 200],
  }}
/>

The DataGrid renders a <Pagination> component (the Sprint 4 companion) below the virtualized scroll. The two layers — pagination boundaries + virtualization windowing — compose naturally: each page is virtualized internally if it's large enough.

import { useState } from 'react';
import { DataGrid, type TableColumn } from '@dashforge/tw';

interface Row {
  id: string;
  name: string;
  email: string;
  status: string;
}

const TOTAL = 200;
const ALL: Row[] = Array.from({ length: TOTAL }).map((_, i) => ({
  id: `r${i}`,
  name: `User ${i + 1}`,
  email: `user${i + 1}@example.com`,
  status: i % 3 === 0 ? 'pending' : 'active',
}));

const COLS: TableColumn<Row>[] = [
  { field: 'name',   header: 'Name',   sortable: true },
  { field: 'email',  header: 'Email' },
  { field: 'status', header: 'Status', sortable: true },
];

function MyGrid() {
  const [page, setPage] = useState(1);
  const [pageSize, setPageSize] = useState(10);
  const start = (page - 1) * pageSize;
  const slice = ALL.slice(start, start + pageSize);

  return (
    <DataGrid
      rows={slice}
      cols={COLS}
      getRowId={(row) => row.id}
      rowHeight={40}
      height="280px"
      totalCount={ALL.length}
      pagination={{
        page,
        pageSize,
        onPageChange: setPage,
        onPageSizeChange: setPageSize,
        pageSizeOptions: [10, 25, 50],
      }}
      sx="w-full max-w-2xl"
    />
  );
}

Customization

DataGrid follows the same sx + slotProps dual-override pattern as Table and every other @dashforge/tw component.

sx — outer wrapper

<DataGrid sx="border-2 border-dashed" {...props} />

slotProps

Available slots (mirror of Table's set, plus DataGrid-specific):

Plus the DataGrid-only stickyLeftCell and stickyLeftHeaderCell internal classes (not exposed via slotProps in v1 — apply via cols[i].sticky: 'left' instead).

Cell renderer library (shared with Table)

Same imports as Table — they work in both:

import {
  RenderText,
  RenderTwoLine,
  RenderChip,
  RenderButton,
  RowActionsMenu,
} from '@dashforge/tw';

RowActionsMenu uses the Sprint 3 <Popover> component + per-action RBAC.

Accessibility

• Semantic <table> element preserved despite virtualization — spacer rows use aria-hidden="true" so screen readers see continuous structure.
• <th scope="col"> on every header.
• aria-sort="ascending" | "descending" | "none" on every sortable header.
• aria-selected on rows when selection is active.
• All interactive controls (sort buttons, checkboxes, search, pagination, row actions) keyboard-accessible via Tab + Enter / Space.
• All built-in label strings translatable via the labels prop (same shape as Table — TableLabels).

i18n (same surface as Table)

Pass t('...') directly to column headers; configure internal default strings via labels:

import { useTranslation } from 'react-i18next';

function UsersGrid() {
  const { t } = useTranslation();

  return (
    <DataGrid
      rows={users}
      cols={[
        { field: 'name', header: t('users.fields.name'), sortable: true, searchable: true },
        // …
      ]}
      getRowId={(r) => r.id}
      rowHeight={48}
      height="600px"
      labels={{
        searchPlaceholder:   t('grid.search.placeholder'),
        selectedCount:       t('grid.selection.count'),  // {count} placeholder
        ariaSelectRow:       t('grid.a11y.selectRow'),
        ariaSelectAllRows:   t('grid.a11y.selectAllRows'),
        ariaSortAscending:   t('grid.a11y.sortAsc'),
        ariaSortDescending:  t('grid.a11y.sortDesc'),
      }}
    />
  );
}

Props

Roadmap

Related

• Table — companion for smaller data sets (≤500 rows) with expandable rows
• Pagination — used by DataGrid's optional internal pagination
• Skeleton — used internally for loading rows
• Customization guide — sx vs slotProps decision tree