gridcn2.0.0
Validation examples

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.

Idle
SKU
Label
CD-100
Cable
CD-200
Charger
CD-300
Dock
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

GateA promise holdsWhile pendingIf it rejects
processPastethe whole pastea newer paste aborts it and runs insteadthe paste does not happen
processCellFromClipboardthe paste, until every cell settlesa newer paste aborts it and runs insteadthe paste does not happen
onBeforeEditStartthe start of the edita newer edit start aborts it and runs insteadthe edit does not start
createRowthe insert, until every row settlesa newer insert aborts it and runs insteadthe insert does not happen
duplicateRowthe duplicate, until every copy settlesa newer duplicate aborts it and runs insteadthe duplicate does not happen
validateRownothing: the write commits firsta newer verdict for the row replaces itthe row gets no verdict
onBeforeDeleteRowsthe deletea newer delete aborts it and runs insteadthe delete does not happen
processReplacethe write of a find-and-replace planthe replace does not write yetthe 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.

On this page