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
| Need | Callback | Page |
|---|---|---|
| Read a data edit, paste, fill, or row change | onDataChange | Data change events |
| Save a change on a server | onSave | Data change events |
| Read a save that the server refused | onSaveRejected | Data change events |
| Cancel a paste | processPaste | Clipboard |
| Cancel a row delete | onBeforeDeleteRows | Data change events |
| Read or control the sort | onSortChange | Sort and filter events |
| Read or control the filters | onFilterChange | Sort and filter events |
| Read or control the quick search text | onSearchTextChange | Sort and filter events |
| Veto an edit before it opens | onBeforeEditStart | Edit and validation events |
| Know how an edit ended | onEditEnd | Edit and validation events |
| Read the cells a bulk write refused | onValidationError | Edit and validation events |
| Read or control the selection | onSelectionChange | Selection and cell events |
| Follow the active cell | onActiveCellChange | Selection and cell events |
| React to a click, double-click, or right-click on a cell | onCellClick, onCellDoubleClick, onCellContextMenu | Selection and cell events |
| Cancel or rewrite a fill | processFill | Fill handle |
| Save or restore the column layout | onColumnLayoutChange | Column and viewport events |
| Show a live width during a resize | onColumnResizing | Column and viewport events |
| Load rows for the rendered range | onRenderedRowsChange | Column and viewport events |
| Read or control the page and the page size | onPageChange, onPageSizeChange | Client pagination |
| Know why a row insert, duplicate, or delete did nothing | onRowActionSkipped | Handle row action results |
| Know that the grid stopped waiting for a gate | onGateAborted | Cancel async gates |
| Pick the row that wins a save conflict | resolveSaveConflict | Handle refused saves |
| Load the values of a header filter from a server | fetchFilterValues | Header 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.
| State | Value prop | Callback | Seed prop |
|---|---|---|---|
| Rows | data | onDataChange | defaultData |
| Sort | sortState | onSortChange | defaultSortState |
| Filters | filterState | onFilterChange | defaultFilterState |
| Quick search | searchText | onSearchTextChange | defaultSearchText |
| Selection | selection | onSelectionChange | defaultSelection |
| Column layout | columnLayout | onColumnLayoutChange | defaultColumnLayout |
Omit the value prop and the grid owns the state. The callback still fires.
Three update rules apply:
- Controlled, you write first:
sortState,filterState, andsearchText. 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 yourdata, it replaces its rows with that array, so passnextback.- Controlled, the grid writes first:
selectionandcolumnLayout. 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:
onBeforeEditStartreturnsfalseto stop an edit.onBeforeDeleteRowsreturnsfalseto stop a row delete.processFillreturnsfalseto stop a fill. It can also return a rewritten text grid. It is synchronous.processPastereturnsfalseto stop a paste.processReplacereturnsfalseto stop a find and replace. It can also return a rewritten plan.createRowreturns the row for an insert. A rejected promise cancels the insert.duplicateRowreturns the row for a duplicate. A rejected promise cancels the duplicate.processCellFromClipboardreturns 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
onFilterChangestill lets thatonPageChangefire. - The grid does not rethrow. It hands the error to
reportError, so the page sees it as an uncaught error. Where the platform has noreportError, 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.
Related
- Data change events
- Selection and cell events
- DataGridProvider
- Events A to Z
- Event log example: a live log of every callback payload