gridcn2.0.0
Events and state

Event shapes

Find the callback for a grid event, and learn how controlled props, seeds, reports, and gates behave.

Every callback on these pages except processFill and processReplace is a prop of DataGrid or DataGridProvider. processFill is an option of useDataGridFill, and processReplace is an option of useDataGridFindReplace. Other add-ons document their own callbacks on their option pages. A callback belongs to a controlled prop, reports an event, or is a gate. The tables below name the callback for each need and link its payload.

Find the callback

NeedCallbackPage
Read a data edit, paste, fill, or row changeonDataChangeData change events
Save a change on a serveronSaveData change events
Read a save that the server refusedonSaveRejectedData change events
Cancel a pasteprocessPasteClipboard
Cancel a row deleteonBeforeDeleteRowsData change events
Read or control the sortonSortChangeSort and filter events
Read or control the filtersonFilterChangeSort and filter events
Read or control the quick search textonSearchTextChangeSort and filter events
Veto an edit before it opensonBeforeEditStartEdit and validation events
Know how an edit endedonEditEndEdit and validation events
Read the cells a bulk write refusedonValidationErrorEdit and validation events
Read or control the selectiononSelectionChangeSelection and cell events
Follow the active cellonActiveCellChangeSelection and cell events
React to a click, double-click, or right-click on a cellonCellClick, onCellDoubleClick, onCellContextMenuSelection and cell events
Cancel or rewrite a fillprocessFillFill handle
Save or restore the column layoutonColumnLayoutChangeColumn and viewport events
Show a live width during a resizeonColumnResizingColumn and viewport events
Load rows for the rendered rangeonRenderedRowsChangeColumn and viewport events
Read or control the page and the page sizeonPageChange, onPageSizeChangeClient pagination
Know why a row insert, duplicate, or delete did nothingonRowActionSkippedHandle row action results
Know that the grid stopped waiting for a gateonGateAbortedCancel async gates
Pick the row that wins a save conflictresolveSaveConflictHandle refused saves
Load the values of a header filter from a serverfetchFilterValuesHeader filter

The grid has no copy event and no scroll-position callback. A paste reports through onDataChange with source: "paste". onRenderedRowsChange reports the rendered rows. A new function identity for onCellClick, onCellDoubleClick, or onCellContextMenu re-renders no cell.

The DataGrid props page lists every prop of DataGridSyncProps.

Three shapes

Controlled and uncontrolled props

A controlled prop and its callback follow the React rule for value and defaultValue. Pass the value prop to control the state. Pass the default prop to seed it once. The grid ignores later changes to a default prop.

StateValue propCallbackSeed prop
RowsdataonDataChangedefaultData
SortsortStateonSortChangedefaultSortState
FiltersfilterStateonFilterChangedefaultFilterState
Quick searchsearchTextonSearchTextChangedefaultSearchText
SelectionselectiononSelectionChangedefaultSelection
Column layoutcolumnLayoutonColumnLayoutChangedefaultColumnLayout

Omit the value prop and the grid owns the state. The callback still fires.

Three update rules apply:

  • Controlled, you write first: sortState, filterState, and searchText. With the value prop, the grid writes nothing, and the callback receives the next value. When you pass the new value, the view changes. Without the value prop, the grid writes the change, then fires the callback.
  • data: the grid applies the change at once and reports it. The next time the grid reads your data, it replaces its rows with that array, so pass next back.
  • Controlled, the grid writes first: selection and columnLayout. The grid applies the gesture and fires the callback at once. A value you pass back that equals the fired value changes nothing. Any other value applies without firing the callback.

For columnLayout, you control each part (widths, order, pins, hidden) on its own. An omitted part stays with the grid.

Callbacks that report

These callbacks say what happened and change nothing. onCellClick, onCellDoubleClick, onCellContextMenu, onActiveCellChange, onColumnResizing, onRenderedRowsChange, onEditEnd, onValidationError, and onSaveRejected only report.

Gates

A gate runs before the grid acts and can stop the action:

  • onBeforeEditStart returns false to stop an edit.
  • onBeforeDeleteRows returns false to stop a row delete.
  • processFill returns false to stop a fill. It can also return a rewritten text grid. It is synchronous.
  • processPaste returns false to stop a paste.
  • processReplace returns false to stop a find and replace. It can also return a rewritten plan.
  • createRow returns the row for an insert. A rejected promise cancels the insert.
  • duplicateRow returns the row for a duplicate. A rejected promise cancels the duplicate.
  • processCellFromClipboard returns the value of a pasted cell. A rejected promise cancels the paste.

onSave is a save acknowledgement. It is neither a reporting callback nor a gate: see onSave.

onBeforeEditStart, onBeforeDeleteRows, processPaste, processReplace, processCellFromClipboard, createRow, and duplicateRow accept a promise. processFill alone is synchronous. A newer request aborts the pending run of the same gate and runs instead, and onGateAborted reports the reason "superseded". A rejection cancels the action. validateRow also accepts a promise. When it rejects, the row gets no verdict.

Callback timing and errors

A callback runs synchronously, after the grid writes the change. Inside the callback, the store holds the new state. One exception: when a filter prop resets a paged grid to page 1, onPageChange(1) runs in a microtask after the sync. With a controlled value prop, the grid writes nothing, and the callback receives the next value.

Every callback runs isolated. If one throws, these rules apply:

  • The change stays written.
  • The other callbacks of the change still run. For example, a filter change resets a paged grid to page 1. A throwing onFilterChange still lets that onPageChange fire.
  • The grid does not rethrow. It hands the error to reportError, so the page sees it as an uncaught error. Where the platform has no reportError, the grid prints [data-grid] <callback> threw: and the error as a console error.

This covers onDataChange, onSave, onSaveRejected, the plugin observers, and every callback of this page. onDataChange and onSave follow the order of Data change events.

On this page