Imperative handle

DataGridComponent accepts a ref typed Ref<DataGridApi<Row>>, for the state and actions that aren't otherwise reachable from outside: the grid's DOM nodes, its live column sizing/order/sort and selection, and the handful of actions every grid ref carries.

import { useRef } from "react";
import { DataGridComponent, type DataGridApi } from "@gridkitjs/react";

const gridRef = useRef<DataGridApi<Row>>(null);

<DataGridComponent ref={gridRef} columns={columns} dataSource={rows} />;

gridRef.current?.scrollToRow("42");
gridRef.current?.getColumnSizing();

Sizing, order, sort, and selection stay uncontrolled exactly as they are without a ref — set their starting values with defaultColumnSizing and friends. DataGridApi is for reading current state and triggering the actions below, not a second way to drive that same state. subscribe doesn't change that either: it's a read/notify channel for reacting to state that already lives here, not a write path.

Elements#

Reading state#

Resolved row and column#

getRows() and getColumns() return ResolvedRow<Row> and ResolvedColumn<Row> — the same shapes the selection events carry, resolved once here so no other doc page repeats them.

ResolvedRow<Row>:

ResolvedColumn<Row>:

Actions#

options on scrollToRow/scrollToColumn is a standard ScrollIntoViewOptions, passed straight through.

Subscribing to state changes#

subscribe(listener: () => void): () => void;

Registers listener to be called after any render in which the grid's internal state may have changed — any getter above may return a different value once it fires, not just one. Returns an unsubscribe function.

Most consumers should reach for one of the use*State hooks built on it instead of calling subscribe directly — each wraps it in useSyncExternalStore so a component elsewhere in the tree stays reactive with no on*Change prop to forward and no polling:

Each hook falls back to an empty/zero value before the grid mounts, the same way its matching getter would if called too early.

See also#

• DataGridComponent for the rest of the component's props.
• Events for callbacks that report the same interactions as they happen, rather than being queried on demand.
• Row grouping for getGroupBy/getGroupExpansion/getDisplayRows/expandAllGroups/collapseAllGroups, in depth.
• Pagination for getPagination/getPageCount/goToPage/nextPage/previousPage/setPageSize, in depth.
• Aggregate functions for getAggregates, and reading a group's own results off getDisplayRows, in depth.