Coming from React Data Grid

This grid takes its API's shape from React Data Grid (7.0.0-beta.60): columns are plain objects, rows an array, the active cell and the sort are props, controlled or not. Most props keep their name. What changes is everything that renders: React Data Grid draws a grid with its own stylesheet, this one hands you the parts and draws nothing. This page maps each of React Data Grid's props and column options onto this grid, and says what your app does where the grid deliberately does nothing.

What changes first

• No CSS, no icons, no text. There is no stylesheet to import and no rdg-light or rdg-dark class: every part takes your className and style, each a value or a function of the part's state ((state) => …). Light and dark are your own CSS. See Styling with Tailwind and Styling with plain CSS.
• Parts instead of one component. <DataGrid /> becomes DataGrid.Root (the data and the scroll container) holding DataGrid.Grid, Header and Body; write the rows and cells out (Rows, Row, Cells, Cell) when you want to style or replace them. See The primitive contract.
• The structure is yours. The same parts render divs or a real <table>: render replaces any part's element (an element, or a function of its props and state). See Tables or divs.
• State is in attributes. The active cell, a selected row, a sorted header carry data-* attributes and ARIA (data-active, data-selected, data-sort, aria-sort), for your CSS. See State attributes.
• No menus, no editors, no checkboxes. The grid owns the behaviour (which cell is edited, which rows are selected, which group is open) and your app renders the controls.
• The grid writes no data. There is no onRowsChange: an edit, a paste, a fill and a row move are events, and your app writes its rows.

// React Data Grid
<DataGrid columns={columns} rows={people} rowKeyGetter={(person) => person.id} />

// this grid
<DataGrid.Root columns={columns} rows={people} rowKey={(person) => person.id} className="h-96">
    <DataGrid.Grid aria-label="People">
        <DataGrid.Header />
        <DataGrid.Body />
    </DataGrid.Grid>
</DataGrid.Root>

DataGrid.Root is the element that scrolls: give it a bounded height, as React Data Grid's container needs one. See Sizing the grid.

The grid's props

Rows and sizes

Sorting and selection

Editing, the clipboard and the fill handle

Columns from the outside

Events

Rendering

The ref

React Data Grid's ref is a handle with element, scrollToCell and setActivePosition (selectCell in earlier betas). Here ref stays the root's element, and a gridRef (useDataGridRef()) is the grid's model and engine, from outside the root:

Inside the root, useDataGrid() returns the same { model, engine }. See Model and engine and the scroll-to-cell example.

Column options

Descending first

A click, Enter or Space on a sortable header cell runs sort-columns.toggle, which cycles ascending, descending, none. For the columns that should start descending, a middleware refuses the toggle and sets the sort it would give instead: the set runs right after the refused toggle, so a controlled Root is asked as for any sort.

import { type SortColumn, veto } from "@fragiola/data-grid-react";

const DESCENDING_FIRST = new Set(["budget", "updatedAt"]);

// descending, ascending, none: the reverse of the grid's own cycle
model.use((ctx, next) => {
    if (
        ctx.command !== "sort-columns.toggle" ||
        !DESCENDING_FIRST.has(ctx.payload.columnKey)
    ) {
        return next();
    }
    const { columnKey, multi = false } = ctx.payload;
    const sorts = ctx.state.sortColumns;
    const current = sorts.find((entry) => entry.columnKey === columnKey);
    const direction = !current
        ? "descending"
        : current.direction === "descending"
          ? "ascending"
          : null;
    // alone, the column replaces the sort; with Ctrl/⌘, it keeps its place among the others
    const others = multi
        ? sorts.filter((entry) => entry.columnKey !== columnKey)
        : [];
    const at = current && multi ? sorts.indexOf(current) : others.length;
    const sortColumns: SortColumn[] = direction
        ? [...others.slice(0, at), { columnKey, direction }, ...others.slice(at)]
        : others;
    // a dry run (`model.check`) changes nothing
    if (!ctx.dryRun) model.run("sort-columns.set", { sortColumns });
    return veto("replaced by sort-columns.set");
});

Column groups

A group is { key, name, children }, as in React Data Grid, with a key of its own (unique among the groups and columns). headerCellClass becomes className on its HeaderCell. A group can move whole (reorderable) and collapse (collapsible, its children's groupShow), with a label that stays in view as the columns scroll. See Column groups and Collapsible groups.

Grouping and trees

TreeDataGrid is no separate component here: one Root shows group rows and a tree's rows through the same row kinds (getRowMeta), and the grid is then a treegrid.

See Row grouping and Tree data.

Master-detail

React Data Grid's master-detail example adds detail rows to the rows, gives them a height with rowHeight and spans them with colSpan. Here a row expands into its own detail: DataGrid.RowDetail inside the row, the expanded rows' keys in expandedRowKeys (with onExpandedRowKeysChange or defaultExpandedRowKeys), and its height in detailHeight (a number, a function of the row, or "auto"). Indexes, counts and getRow stay those of your rows. See Master-detail.

Exports with no counterpart

What this grid adds

• Rows by index. rowCount and getRow(index) stand for a dataset you do not hold: rows not loaded keep their room, and the windows tell you what to load. See Loading data.
• Millions of rows and columns. Past the browser's size limit, scroll scaling maps the scrollbar onto the whole dataset, on both axes. See Scroll scaling.
• Ranges of cells. Shift with the keys, a drag or Shift+click select a range, copied and pasted as tab-separated text. See Cell selection.
• Rows as tall as their content. rowHeight="auto" measures each row as it renders. See Measured heights.
• Collapsible column groups with labels that stay in view. See Collapsible groups.
• Row reordering by the grid. onRowMove turns it on: a drag on your handle (useRowDragHandle) or Ctrl+Shift+↑ and ↓. See Row reordering.

The examples side by side

Each example of React Data Grid's website, and the one here that does the same: