Async gates example
Ask a server before the grid acts on a paste, an edit start, a row insert, or a row rule, and see the grid wait for the answer.
A gate is a prop function that the grid calls before it acts. Some checks need a server before the grid acts. A paste can need normalizing. A new row can need an id from the server. Each of these props accepts a function that returns a value or a promise. The grid holds the gesture until the promise settles, then writes once.
In this grid, processPaste upper-cases pasted SKUs on the server, createRow waits for a server id, and validateRow flags a taken SKU. Paste lower-case text, add a row, or type AB-100 in the SKU column. The status line shows the pending call.
Paste lower-case SKUs: the server upper-cases them before they land. Type AB-100 or AB-200 in the SKU column: the server check flags the cell after the edit commits. Add a row: the id comes from the server.
pnpm dlx shadcn@latest add @gridcn/data-grid-async-gates-demo
Return a promise
This provider uses the three gates of the demo:
import {
DataGridBody,
DataGridHeader,
DataGridProvider,
DataGridRoot,
defineColumns,
} from "@/components/data-grid/data-grid";
type Sku = { id: string; sku: string };
const columns = defineColumns<Sku>()([
{ id: "sku", header: "SKU", accessorKey: "sku" },
]);
const rows: Sku[] = [{ id: "r1", sku: "CD-100" }];
export function SkuGrid({ api }: { api: SkuApi }) {
return (
<DataGridProvider
defaultData={rows}
columns={columns}
getRowId={(row) => row.id}
processPaste={async ({ cells }) => api.normalize(cells)}
createRow={async () => ({ id: await api.newId(), sku: "" })}
validateRow={async (row) =>
(await api.isTaken(row.sku)) ? { sku: "SKU is already taken" } : null
}
>
<DataGridRoot>
<DataGridHeader />
<DataGridBody />
</DataGridRoot>
</DataGridProvider>
);
}
type SkuApi = {
normalize: (cells: string[][]) => Promise<string[][]>;
newId: () => Promise<string>;
isTaken: (sku: string) => Promise<boolean>;
};What a pending promise does
| Gate | A promise holds | While pending | If it rejects |
|---|---|---|---|
processPaste | the whole paste | a newer paste aborts it and runs instead | the paste does not happen |
processCellFromClipboard | the paste, until every cell settles | a newer paste aborts it and runs instead | the paste does not happen |
onBeforeEditStart | the start of the edit | a newer edit start aborts it and runs instead | the edit does not start |
createRow | the insert, until every row settles | a newer insert aborts it and runs instead | the insert does not happen |
duplicateRow | the duplicate, until every copy settles | a newer duplicate aborts it and runs instead | the duplicate does not happen |
validateRow | nothing: the write commits first | a newer verdict for the row replaces it | the row gets no verdict |
onBeforeDeleteRows | the delete | a newer delete aborts it and runs instead | the delete does not happen |
processReplace | the write of a find-and-replace plan | the replace does not write yet | the replace does not happen |
The import gate holds the import dialog while it parses or validates. mapColumn and the createRow of the import also accept a promise, and the import dialog waits for it. See Import. A function that returns a plain value acts in the same call. processPaste returns false and onBeforeEditStart returns false to cancel.
The grid reads its state again when the promise settles. It discards the result without an error in these cases:
- Paste: the grid is
readOnly, a cell is in edit, the sort or filter changed, or a target row left the data. - Insert: the grid is
readOnly, or the row beside the insert left the data. A duplicate skips each source row that left. - Edit start: the grid is
readOnly, the cell is gone, or the user moved to another cell. - Delete: the grid is
readOnly, or the rows or checked rows changed. - Row verdict: the row left the data.
A row that moved keeps its gesture, because the grid follows the row id. While a promise is pending, a newer request of the same kind aborts the pending one and runs instead.
The grid also passes an AbortSignal to every gate. Cancel async gates covers the signal, gateTimeoutMs, and the pending state.
Client and server modes
A held gesture emits one change when the promise settles. A refetch that removes a row cancels the gesture on it, because the grid drops the result for a row that left. With sortMode="server", the grid never reorders rows when a promise settles. The server owns the order. For a server grid, see the async gates of the server contract.
Related
- Cancel async gates: the signal, the timeout, and the pending state
- Async validation example: a schema that returns a promise
- Cross-field validation example:
validateRow - Change copy and paste:
processPasteandprocessCellFromClipboard - Row operations:
createRowandduplicateRow
Cross-field validation example
Flag a cell with a row rule that compares two columns, judged once after a whole edit, paste, or fill commits.
Server rows example
Send sort, filter, search, and page to your server with one fetchRows function, and see stale-request aborts, server pushes, and revalidation.