Documentation
Concepts

Model and engine

The model holds the grid's data and rules and changes only through commands; the engine is the grid on screen, scrolling and focus.

The core splits a grid in two, and the React package wires them to your props.

The model

The model is the grid's data and its rules: the columns, where the rows come from, the sizes and the active cell. It is plain data, it runs in Node, and it changes only through commands. Every command runs through a chain of middleware that can let it pass, rewrite its payload or veto it.

Everything has the same verbs, each taking a key and a payload:

verbdoes
runruns a command and commits it: model.run("active-position.set", { rowIndex: 3, columnIndex: 1 })
canwhether a command would apply now (nothing is committed)
checkwhat a command would return now (nothing is committed)
getreads a value: model.get("row-count"), model.get("row-by", { index: 3 })
isanswers a question: model.is("cell-active", { rowIndex: 3, columnIndex: 1 })
useadds a middleware
subscribelistens to every committed command

Commands are named by the state they change, a dot, then the change: columns.set, sort-columns.toggle, selected-rows.toggle, column-widths.resize (resizing's), active-position.move and the rest of the CommandMap type, which lists every one with its payload and result. A command never throws on bad input: it returns { ok: false, error }. A command the grid does not know (one of a feature that is not installed, say) returns the error not_found.

The keys are the core's and the installed features': sort-columns.toggle is sorting's, and is typed only on a grid that installs sorting().

middleware.ts
import { veto } from "@fragiola/data-grid-react";

// rows 0–9 are read-only: their cells cannot become active
model.use((ctx, next) =>
    ctx.command === "active-position.set" && ctx.payload.rowIndex < 10
        ? veto("locked")
        : next(),
);

The engine

The engine is one grid on screen. It measures the root, reads the scroll, computes the windows, writes the layers' positions, maps the keys onto commands and moves focus. It also has the verbs: engine.get("row-window"), engine.run("scroll-to-cell", { rowIndex: 500 }) and engine.subscribe("rows-end-reached", listener).

From props to commands

DataGrid.Root creates both and maps its props onto commands: columns becomes columns.set, rows (or rowCount and getRow) becomes data.set, and an installed feature maps its own (activePosition becomes active-position.set with navigation, sortColumns becomes sort-columns.set with sorting). useDataGrid() returns { model, engine } to any part inside it, so an app can read and drive the same grid from code. Its keys are typed by the core's alone, unless it is given the features: useDataGrid<Person, typeof features>().

From outside the root

A toolbar, a status bar or a data cache usually lives beside the grid, not inside it. Give the root a gridRef from useDataGridRef(): it is the root's model and engine while the root is mounted, and null otherwise. ref stays the root's element.

status-bar.tsx
import {
    DataGrid,
    type DataGridRef,
    useDataGridRef,
    useRowWindow,
} from "@fragiola/data-grid-react";

function StatusBar({ gridRef }: { gridRef: DataGridRef<Person> }) {
    // re-renders this component when the rows in view change, never the grid
    const { visible } = useRowWindow(gridRef);
    return (
        <p>
            Rows {visible.start + 1}–{visible.end}
        </p>
    );
}

export function People() {
    const gridRef = useDataGridRef<Person>();
    return (
        <>
            <StatusBar gridRef={gridRef} />
            <button
                type="button"
                onClick={() =>
                    gridRef.current?.engine.run("scroll-to-cell", { rowIndex: 0 })
                }
            >
                Back to the top
            </button>
            <DataGrid.Root columns={columns} rows={people} gridRef={gridRef}>
                {/* … */}
            </DataGrid.Root>
        </>
    );
}

Unlike a plain ref, a gridRef tells when a root takes or releases it, so the hooks that take one follow the grid from anywhere: useDataGrid(gridRef) ({ model, engine }, or null until a root holds it), useRowWindow(gridRef) and useColumnWindow(gridRef) (the empty window until then). Only the component calling them re-renders. A gridRef belongs to one mounted root at a time; outside a component (a module, a store, a test), make one with createDataGridRef(). Both take the features after the row (useDataGridRef<Person, typeof features>()) to type the features' keys. The large-dataset example shows its windows this way.

Controlled or not

With navigation() installed, defaultActivePosition starts the active cell and lets the grid move it. activePosition controls it: a key press asks, through onActivePositionChange, and only the prop moves it. See the keyboard-navigation example. The sort (sortColumns, with sorting installed) and the expanded rows (expandedRowKeys, with row expansion installed) work the same way.