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
| Type | Shape | Meaning |
|---|---|---|
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. |
ViewCellRef | CellRef & { 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. |
ViewIndex | A branded number | A 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. |
CellErrorEntry | CellErrorTarget & { 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
| Type | Shape | Meaning |
|---|---|---|
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
| Type | Shape | Meaning |
|---|---|---|
DataOp<TData> | An update, insert, delete, or move operation | One 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
| Type | Shape | Meaning |
|---|---|---|
GateName | A union of the gate names | processPaste, 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. |
RowActionSkipReason | A union of the skip reasons | Why 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. |
ColumnOrderSkipReason | A union of the skip reasons | Why 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 } | void | The 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
| Type | Shape | Meaning |
|---|---|---|
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. |
FilterOperator | BuiltInFilterOperator | string | A built-in operator, or the id of a custom operator. |
BuiltInFilterOperator | A union of 15 operator names | The built-in operators, for example contains, gt, isBetween, and isAnyOf. |
FilterNode | FilterSpec | FilterGroup | One 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
| Type | Shape | Meaning |
|---|---|---|
GridActions | An interface of the named keyboard actions | Extend it by declaration merging. |
GridAction | keyof GridActions | Every named action, built in or merged. |
Keymap | Partial<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
| Type | Shape | Meaning |
|---|---|---|
DataGridApi<TData> | { actions, store, scrollTo, focus, runShortcut, getSelection, getRow, getViewRowIds } | The handle that ref and useDataGridApi give. |
DataGridActions | The mutations of one grid | The 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. |
DataGridStore | The state of one grid | The 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. |
DataGridReadState | The state that store.getState() returns | The argument of exportGrid and printGrid. |
Data grid props lists the members of the handle.
Plugins
| Type | Shape | Meaning |
|---|---|---|
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. |
RowBandRenderCtx | The layout of one band | The argument of render. |
DataGridPluginCtx<TData> | { api } | The context of the onDataChange observer. |
OverlayPluginCtx | The window and pin helpers | The 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
| Type | Shape | Meaning |
|---|---|---|
GridEditEndEvent | ViewCellRef & { 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.
Related
- DataGrid props: the props that take these types.
- Event shapes: the callback for each event.
- Store hooks: the hooks that return them.
- TypeScript generics: type arguments and augmentation.
State and view index
Learn how the grid addresses rows and columns by data index, view index, and id, which APIs take which address, and why a view index goes stale.
Layout and display types
Look up the shape of the types that describe the column layout, the row markers, the empty, loading, and error states, and the column helpers.