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:
| verb | does |
|---|---|
run | runs a command and commits it: model.run("active-position.set", { rowIndex: 3, columnIndex: 1 }) |
can | whether a command would apply now (nothing is committed) |
check | what a command would return now (nothing is committed) |
get | reads a value: model.get("row-count"), model.get("row-by", { index: 3 }) |
is | answers a question: model.is("cell-active", { rowIndex: 3, columnIndex: 1 }) |
use | adds a middleware |
subscribe | listens 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().
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.
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.