gridcn2.0.0
Types and hooks

Exported types

Look up the shape of the types that the data-grid module exports, such as CellRef, SelectionState, DataChange, GridCommand, and ColumnLayout.

The data-grid module exports these types next to the components and hooks. Import them from @/components/data-grid/data-grid. Each table gives the shape and the meaning of a type, and most link the page that uses it. The types of columns, cell types, and cell callbacks live on ColumnDef, the CellType contract, and Event shapes. Layout and display types covers ColumnLayout, the marker modes, and the display states.

Addresses

TypeShapeMeaning
CellRef{ rowId, columnId }The stable identity of a cell: the row id from getRowId plus the column id. A sort, a filter, or a reorder never changes it. Cell actions such as selectCell and startEditing take a CellRef. Each has an *At variant, such as selectCellAt, that takes a ViewCoord. A ref whose row or column is not in the view does nothing, and development mode warns once.
ViewCoord{ col, row }A cell position in view index. row is the position in the sorted and filtered list. col is the position among the visible columns, without the marker column. When the view changes, the position moves. Store a CellRef instead.
ViewCellRefCellRef & { viewRowIndex, viewColumnIndex }A CellRef plus the view position of the cell at the time of the event. onActiveCellChange, onBeforeEditStart, and onEditEnd deliver it.
GridRect{ x, y, width, height }A rectangle of cells. It covers the columns x to x + width - 1 and the rows y to y + height - 1.
ViewIndexA branded numberA row position in the current view. viewIndex(index) and viewIndexes(list) mark a number as a view row position, so that your code shows which address it holds. The At actions also take plain numbers. A number passed to an id action, such as deleteRows([4]), warns in development and does nothing.
CellErrorTarget{ rowId, columnId }A cell that clearCellErrors names.
CellErrorEntryCellErrorTarget & { message }A cell and its error message for setCellErrors.

Data grid props lists the handle members that take a CellRef, such as scrollTo. This sample keeps a CellRef across a sort and deletes the top two view rows through viewIndexes:

import {
  viewIndexes,
  type CellRef,
  type DataGridActions,
} from "@/components/data-grid/data-grid";

export function restoreCell(actions: DataGridActions, saved: CellRef) {
  actions.selectCell(saved);
}

export function deleteTopTwo(actions: DataGridActions) {
  return actions.deleteRowsAt(viewIndexes([0, 1]));
}

Selection

TypeShapeMeaning
CellRange{ start, end }Two CellRef corners of a rectangle, in either diagonal order.
SelectionState{ anchor, range, rangeStack, rowIds, columnIds }The selection in stable terms. It is the payload of onSelectionChange. The active cell is not part of it. The selection and defaultSelection props, getSelection, and setSelection use it too.
GridSelection{ current, rows, columns }The selection in view index. current holds cell, range, and rangeStack.
SelectLineActionOptions{ additive?, extendFromLast?, from? }The options of selectRow and selectColumn. additive toggles the line and keeps the rest. extendFromLast selects from the last line. from names that line.

Selection and cell events lists the callbacks.

Data changes

TypeShapeMeaning
DataOp<TData>An update, insert, delete, or move operationOne row operation, addressed by row id.
RowPatch{ rowId, changes }One whole-row update for actions.updateRows. changes maps column ids to new values.
CellPatch{ rowId, columnId, value }One cell write for actions.updateCells, addressed by row id and column id. The grid skips an unknown id.
DataChange<TData>{ ops, source, label?, reverts?, serverRowIds? }One batch of operations with its origin.

Operation engine contract covers applyChange and invertChange. Data change events covers source.

Gates and saves

TypeShapeMeaning
GateNameA union of the gate namesprocessPaste, processCellFromClipboard, validateRow, onBeforeEditStart, createRow, duplicateRow, onBeforeDeleteRows, import, mapColumn, processReplace, validate, processFill, and resolveTexts.
GateContext{ signal }The argument of an async gate. signal aborts when the grid stops waiting.
RowActionSkipReasonA union of the skip reasonsWhy a row action did nothing: readOnly, unloaded-rows, no-factory, gate-declined, gate-threw, nothing-to-do, view-ordered, group-row, server-groups, disabled, all-matching, or hidden-rows-only.
RowActionResult{ ok: true } | { ok: false, reason }What the insert, duplicate, and delete actions return: ok once the action ran or an async gate started, else the RowActionSkipReason.
ColumnOrderSkipReasonA union of the skip reasonsWhy setColumnOrder did not move: disabled, unknown-column, not-reorderable, pin-zone, or nothing-to-do. pin-zone means the target sits in another pin zone, or a group's members span two zones.
ColumnOrderResult{ ok: true } | { ok: false, reason }What setColumnOrder and canSetColumnOrder return: ok when the move changes the order, else the ColumnOrderSkipReason.
CellValidateContext{ rows, batch, valueOf }The third argument of a function validate. It holds the rows before the write, the cells of the column that the write sets, and the value reader of the column.
UniqueOptions{ message?, ignoreCase? }The options of unique().
SaveResolution"theirs" | "mine" | { row } | voidThe answer of resolveSaveConflict: take the server row, keep the grid row, or save a merged row. Nothing (void) takes the server row.

Sort and filter

TypeShapeMeaning
SortSpec{ columnId, direction }One sort. direction is "asc" or "desc".
FilterSpec{ filterId?, columnId, operator, value? }One filter row. value is a string, a pair, or a list, by operator.
FilterOperatorBuiltInFilterOperator | stringA built-in operator, or the id of a custom operator.
BuiltInFilterOperatorA union of 15 operator namesThe built-in operators, for example contains, gt, isBetween, and isAnyOf.
FilterNodeFilterSpec | FilterGroupOne entry of filterState.
FilterGroup{ filterId?, join, filters }Filters that match together. join is a FilterJoinOperator, "and" or "or".
FilterOperatorInput"none" | "single" | "range" | "list"The value shape that a filter operator takes.
FilterValue{ value, label?, count? }One value that fetchFilterValues offers to a set filter.
SearchOptions{ matchCase?, wholeCell? }The options of the quick search.
SearchMatch{ row, columnId }One quick-search hit. row is the position in the whole sorted and filtered view, also on a paged grid.
CellTypeFilter{ operators?, match?, compare?, valueInput?, matchCase? }The filter capabilities of a cell type. compare(text, bound) orders cell text against a bound for gt, gte, lt, lte, and isBetween.
CellTypeValueInput"text" | "number" | "date" | "boolean" | "choices"The built-in widget of a filter value.
FilterValueInputProps{ column, operator, value, onValueChange }The props of a custom valueInput component.

createFilterMatcher(filter, options?) parses the bounds of a FilterSpec once. It returns a (text: string) => boolean matcher. options.compare orders text against a bound. options.custom evaluates a custom operator. The grid's built-in text filter uses the same matcher. A column or a cell type with filter.match filters with that function instead. CellType contract covers the filter members.

Commands and keys

TypeShapeMeaning
GridActionsAn interface of the named keyboard actionsExtend it by declaration merging.
GridActionkeyof GridActionsEvery named action, built in or merged.
KeymapPartial<Record<GridAction, KeyBinding[]>>Key bindings by action.
GridCommand<TData>{ run, when?, scope?, label?, group? }A custom command. scope is "grid", "editing", or "always".
GridCommandCtx<TData>{ api, cell, viewRowIndex, viewColumnIndex, row, readOnly }The context of run and when.
CommandGroup"navigation" | "selection" | "editing" | "clipboardFill" | "history" | "other"The sections of the keybindings dialog.

Shortcut remapping shows them in use.

Handle and store

TypeShapeMeaning
DataGridApi<TData>{ actions, store, scrollTo, focus, runShortcut, getSelection, getRow, getViewRowIds }The handle that ref and useDataGridApi give.
DataGridActionsThe mutations of one gridThe actions member of DataGridApi. useDataGridActions returns the same object. Actions A to Z lists its methods.
DataGridStoreWrapper{ getState, getInitialState, subscribe }The store member of DataGridApi.
DataGridStoreThe state of one gridThe full state of one grid, callbacks included, as the store of useDataGridStoreProps holds it. data is typed as readonly unknown[].
DataGridStoreStateOf<TData>DataGridStore without its engine fields, with data: readonly TData[]The state view that a selector reads, with data typed to your row type.
DataGridReadStateThe state that store.getState() returnsThe argument of exportGrid and printGrid.

Data grid props lists the members of the handle.

Plugins

TypeShapeMeaning
DataGridPlugin<TData>{ name, Overlay?, rowBands?, onDataChange?, commands?, keymap?, Mount? }One entry of the plugins prop.
PluginRowBands{ top?, bottom?, render }The rows a plugin adds above and below the data.
RowBandRenderCtxThe layout of one bandThe argument of render.
DataGridPluginCtx<TData>{ api }The context of the onDataChange observer.
OverlayPluginCtxThe window and pin helpersThe props of an Overlay component.
OverlayRectProps{ ctx, rect, className?, style? }The props of OverlayRect, which paints one GridRect of an Overlay. data-grid-sdk exports both.
PinTrackData{ pins, trackLefts, trackRights, renderedUnpinnedRange }The pin and track data per column that an overlay segment needs to sit over a pinned cell.
RectSegment{ rect, pin?, pinStyle? }One pin zone of a GridRect, with the style of a pinned zone. The unpinned middle segment has no pin.

Plugin API covers the members.

Events

TypeShapeMeaning
GridEditEndEventViewCellRef & { result }The argument of onEditEnd. result is "commit", "cancel", or "rejected".
GridBulkValidationError{ rowId, columnId, viewRowIndex, value, message }One cell that a bulk write refused.
GridValidationErrorEvent{ source, rejected }The argument of onValidationError. source is "paste", "fill", "stream", "replace", "delete", "cut", or "edit".
ClipboardProcessCtx<TData>{ row, column }The row and the column that processCellForClipboard and processCellFromClipboard share.
UseDataGridClipboardOptions{ sanitizeFormulas? }The options of useDataGridClipboard. sanitizeFormulas prefixes formula-like cells with ' in the copied text.

Edit and validation events lists the moment each one fires.

On this page