Gate cancellation and timeouts
Abort the request of a slow gate with its signal, set a timeout for every gate, and show the pending state while a gate waits.
A gate is a callback that runs before the grid acts, such as processPaste or onBeforeEditStart. A gate can return a promise, and the grid waits for it. This page shows how to stop that wait: pass the AbortSignal of the gate to your request, set gateTimeoutMs, and read the pending state. Async gates example runs the gates live.
Cancel a request with the signal
Every gate receives an AbortSignal as its last argument. The signal aborts in these cases:
- A newer run of the same gate replaces the run. The newer request always wins. For example, the user edits a row again before
validateRowsettles for the row, or the user pastes again beforeprocessPastesettles. - The grid unmounts.
- The result cannot apply. For example, the grid turned
readOnly, or the row is gone. gateTimeoutMsruns out.- The user presses Escape while
onBeforeEditStartwaits.
Pass the signal to fetch, and the request stops when the signal aborts. Pass the function as the processPaste prop:
async function processPaste({
cells,
signal,
}: {
cells: string[][];
signal: AbortSignal;
}) {
const response = await fetch("/api/normalize", {
method: "POST",
body: JSON.stringify(cells),
signal,
});
return response.ok ? response.json() : false;
}The grid drops an aborted gate result. A rejection after an abort adds no warning, so an AbortError from fetch needs no catch.
| Gate | Signal position |
|---|---|
processPaste | ({ cells, target, signal }) |
processCellFromClipboard | (text, { row, column, fromText, signal }) |
validateRow | (row, rowId, { signal }) |
onBeforeEditStart | (cell, { signal }) |
createRow | (index, { signal }) |
duplicateRow | (row, index, { signal }) |
onBeforeDeleteRows | ({ rowIds, hiddenCount, signal }) |
processReplace | ({ plan, signal }) |
mapColumn | (header, index, { signal }) |
processFill | ({ source, target, cells, signal }) |
resolveTexts | (texts, options, { signal }) |
gateTimeoutMs covers every gate in the table. It also covers an async schema in validate that holds a paste, a fill, or a clear. That schema receives no signal, so the grid drops its late answer. A gate that ignores the extra argument keeps working.
Stop waiting for a slow gate
A gate waits for its promise. Set gateTimeoutMs to abort a gate whose promise has not settled in time. The signal aborts, the grid cancels the action, and the next action can start. Pass one number for every gate, or an object with a number for each gate name. Pass the value as the gateTimeoutMs prop of DataGridProvider. This grid aborts a paste gate after 10 seconds and an edit gate after 3 seconds, and logs each abort:
import {
DataGridBody,
DataGridHeader,
DataGridProvider,
DataGridRoot,
defineColumns,
} from "@/components/data-grid/data-grid";
type Row = { id: string; name: string };
const columns = defineColumns<Row>()([
{ id: "name", header: "Name", accessorKey: "name" },
]);
async function processPaste({
cells,
signal,
}: {
cells: string[][];
signal: AbortSignal;
}) {
const response = await fetch("/api/normalize", {
method: "POST",
body: JSON.stringify(cells),
signal,
});
return response.ok ? ((await response.json()) as string[][]) : false;
}
export function TimedGrid({ rows }: { rows: Row[] }) {
return (
<DataGridProvider
defaultData={rows}
columns={columns}
processPaste={processPaste}
gateTimeoutMs={{ processPaste: 10_000, onBeforeEditStart: 3_000 }}
onGateAborted={({ gate, reason }) => console.warn(gate, reason)}
>
<DataGridRoot className="h-80">
<DataGridHeader />
<DataGridBody />
</DataGridRoot>
</DataGridProvider>
);
}onGateAborted({ gate, reason }) fires once for every gate that the grid stopped waiting for. reason is one of these:
| Reason | Meaning |
|---|---|
"timeout" | The gate ran longer than gateTimeoutMs. |
"changed" | The rows, the checked rows, or readOnly changed while the gate waited. The active cell moved while onBeforeEditStart waited, or an edit started while processPaste waited. |
"superseded" | A newer run of the same gate replaced it. |
"cancelled" | The user pressed Escape while onBeforeEditStart waited. |
"reset" | The grid reset or unmounted. |
gateTimeoutMs is off by default: a gate waits for its promise.
Show the pending state
useDataGridGatePending() returns the set of gate names whose promise has not settled. The set can hold "import" while the import dialog parses or validates, and "processReplace" while that hook runs. gateTimeoutMs does not cover import. Call the hook inside the provider:
import { useDataGridGatePending } from "@/components/data-grid/data-grid";
function PendingLabel() {
const pending = useDataGridGatePending();
if (!pending.has("processPaste")) return null;
return <span>Normalizing the paste</span>;
}The set is empty while no gate runs. The grid root also sets data-gate-pending while a gate runs. The value lists the gate names, separated by spaces, for example data-gate-pending="processPaste validateRow". A running gate does not set aria-busy on the root. The root carries aria-busy only while loading is true. Style the busy grid with CSS on [data-gate-pending].
Related
- Async gates example: a live grid with three gates
- Change copy and paste:
processPasteand its signal - Row validation and async checks:
validateRowand its signal - Row operations:
onBeforeDeleteRows - Edit and validation events: the gate callbacks and their context