gp-grid-logo
API Reference

Events

Reference for grid instructions, lifecycle hooks, and DOM-style events emitted by the React Grid component for selection, sorting, and editing flows today.

gp-grid reports column and row interactions as identity-bearing objects. Callbacks receive one event argument.

Column and row interactions

interface ColumnMovedEvent {
  columnId: string;
  fromViewIndex: number;
  toViewIndex: number;
}

interface ColumnResizedEvent {
  columnId: string;
  width: number;
  viewIndex: number;
}

interface ColumnPinnedEvent {
  columnId: string;
  pinned: "start" | "end" | null;
}

interface RowDragEndEvent {
  rowId: RowId;
  fromViewIndex: number;
  toViewIndex: number;
}

interface RowResizedEvent {
  rowId: RowId;
  height: number;
  viewIndex: number;
}

Indices refer to the resolved view. Use identities when persisting state across sorting, filtering, or schema changes. The core owns live column state; the row-drag consumer remains responsible for reordering its mutable source.

<Grid
  columns={columns}
  dataSource={dataSource}
  rowHeight={36}
  onRowDragEnd={({ fromViewIndex, toViewIndex }) => {
    dataSource.moveRow(fromViewIndex, toViewIndex);
  }}
  onColumnResized={({ columnId, width }) => {
    console.log(columnId, width);
  }}
/>

Write events

onCellValueChanged fires per changed cell and includes rowId, columnId, colIndex, field, oldValue, newValue, and rowData. Configure getRowId to enable it.

onWriteCommitted fires once per edit, paste, fill, cells.setValue, undo, or redo. Its changes are addressed by record and column identity, and skipped lists targets that were refused. It also requires getRowId.

onWriteRejected reports the refused target, its reason, and operation. Numeric editor drafts are coerced by cellDataType; invalid drafts report type-mismatch. Columnar sources report read-only-source; group and total rows report not-a-record.

See write commands and history for event fields, skip semantics, and opt-in undo/redo.

Schema and hierarchy events

  • onColumnSchemaRejected: rejected column/group schema; the previous schema remains active.
  • onFrozenRowsChanged: effective frozen count or limiting reason changed.
  • onRowGroupToggled: a pointer or key gesture changed group expansion.
  • onRowGroupingRejected: grouping cannot apply to the bound source.

See column groups, frozen rows, and row grouping.

Transaction notifications

Mutable sources expose subscribe(listener) and the onTransactionProcessed factory option. The result includes added, removed, and updated counts plus identity-addressed change details. Framework wrappers refresh from that result automatically.

const { dataSource } = useGridData(data, { getRowId: (row) => row.id });
const unsubscribe = dataSource.subscribe((result) => console.log(result));

Core instructions

For a custom adapter, subscribe with core.onBatchInstruction(listener) and consume the exported GridInstruction union. Layout snapshots, header bands, column windows, and row regions are published by the core. MOVE_SLOT includes a required height; row and column windows use exclusive end indices.

const unsubscribe = core.onBatchInstruction((instructions) => {
  console.log(instructions);
});

See geometry and the custom adapter migration before implementing an instruction consumer.