Handle row action results
Read why a row action did nothing, and stop an async gate that never settles with gateTimeoutMs and onGateAborted.
insertRow, insertRows, duplicateRows, duplicateRowsAt, deleteRows, and deleteRowsAt can do nothing. They tell you why. A gate such as onBeforeDeleteRows can also wait forever. This page covers both. See Change server rows for the actions.
In this demo, onBeforeDeleteRows asks a slow mock server, and gateTimeoutMs stops the wait after 2 seconds. The log shows each result, skip, and aborted gate:
Click Delete first row twice, delete the locked second row, insert a row without a createRow factory, or turn on read-only. Pick the slow server: the gate times out after 2000 ms.
- No action yet.
Read the result of an action
Each of the six row actions returns { ok: true } once it ran or an async gate started. Otherwise it returns { ok: false, reason }. The reason names the cause:
reason | Meaning |
|---|---|
"readOnly" | The grid is read-only. |
"unloaded-rows" | A target row is not loaded. A delete still removes the loaded rows. It returns this reason only when no target row is loaded. |
"no-factory" | createRow or duplicateRow is missing. |
"gate-declined" | onBeforeDeleteRows returned false, or its promise resolved with false. |
"gate-threw" | onBeforeDeleteRows, createRow, or duplicateRow threw or rejected. |
"nothing-to-do" | No target row matched, count was 0, or a row move had nowhere to go. |
"view-ordered" | A row move was refused because an active sort or filter owns the row order. |
"group-row" | An insert or a duplicate started on a group row, which holds no data. |
"server-groups" | Insert, duplicate, delete, or move ran while the server owns the groups (groupMode="server"). The grid does not hold the rows of a whole group. |
"all-matching" | A key or menu row action found all matching on, so the checked rows are not in the grid. |
"hidden-rows-only" | A key or menu row action found only checked rows that the view does not show. |
"disabled" | A row move shortcut ran without a reorder rowMarkers mode. |
A call with source: "stream" returns { ok: true } when no id matched, because a server push can repeat a delete.
onRowActionSkipped({ action, reason, count }) fires for every skip of insertRows, duplicateRows, deleteRows, or moveRows. A shortcut, a drag, a menu item, or a call can start the action. One handler shows a message for all four.
count holds the number of unloaded rows that a delete skipped.
A new insert, duplicate, or delete aborts the previous one while its promise has not settled. onGateAborted reports "superseded", and the grid drops the earlier result.
These cases differ:
- A
deleteRowscall withsource: "stream"never fires it. insertRowreports the action as"insertRows",deleteRowsAtas"deleteRows", andduplicateRowsAtas"duplicateRows".- Insert row with no active cell reports nothing, even in a read-only grid.
- Duplicate row and Delete rows with no selection and no active cell report nothing when no reason applies.
Disabled row items of the context menu show the reason as a tooltip.
This grid maps the reason to a message. Pass the handler to DataGrid or DataGridProvider:
"use client";
import { useState } from "react";
import {
DataGrid,
defineColumns,
type RowActionSkipReason,
} from "@/components/data-grid/data-grid";
type Order = { id: string; customer: string };
const columns = defineColumns<Order>()([
{ id: "customer", header: "Customer", accessorKey: "customer" },
]);
const MESSAGES: Partial<Record<RowActionSkipReason, string>> = {
readOnly: "The grid is read-only.",
"unloaded-rows": "Scroll to the rows first.",
"view-ordered": "Clear the sort or filter to move rows.",
"all-matching": "Use your server to act on all matching rows.",
};
export function OrdersGrid({ rows }: { rows: Order[] }) {
const [message, setMessage] = useState<string>();
return (
<>
<DataGrid
defaultData={rows}
columns={columns}
getRowId={(row) => row.id}
onRowActionSkipped={({ reason }) => setMessage(MESSAGES[reason])}
/>
<p role="status">{message}</p>
</>
);
}reorderRows and moveRowsBy return true or false and report their skips as action: "moveRows".
Stop a gate that never settles
Set gateTimeoutMs to abort an async gate whose promise has not settled in time. The gates are onBeforeDeleteRows, validateRow, onBeforeEditStart, createRow, duplicateRow, processPaste, processCellFromClipboard, processReplace, the import mapColumn, and an async column validate. The import step has no timeout, but its mapColumn gate has one. Pass one number, or a number per gate name. The default is off. This prop gives the delete gate two seconds and sets no limit for the others:
gateTimeoutMs={{ onBeforeDeleteRows: 2000 }}onGateAborted({ gate, reason }) reports each gate the grid stopped waiting for. The reason is "timeout", "changed", "superseded", "cancelled", or "reset".
Related
- Row operations: the gates and the factories
- Change server rows: the actions on server rows
- Data change events: the row operations that a change reports