Async validation example
Check a value against a server with a Standard Schema that returns a promise, and see a single edit and a bulk paste wait for the answer.
The SKU column is the fourth column. It runs a fake uniqueness check with about 800 ms of latency. SKU-001 and SKU-002 already exist. Type a SKU and press Enter to see the pending state. Paste several SKUs to see the bulk path.
| Column | Rule | Kind |
|---|---|---|
| Age | 18 or older. Also fires a toast. | Blocking |
| Must contain an @. | Blocking | |
| SKU | SKU-001 and SKU-002 are taken. The check takes about 800 ms and the input is read-only meanwhile. | Blocking |
| Price | Must be a number. A decimal commits rounded: 42.9 becomes 43. | Blocking |
| Notes | At most 12 characters. | Soft |
| Zod Score | Integer from 0 to 100. | Blocking |
| Joi Code | Uppercase letters, digits, or dashes. | Blocking |
| Valibot Tag | At least 3 characters. | Blocking |
- Every message: hover the cell to read it, also while the editor is open (the browser shows it as a native tooltip).
- Blocking rule: Enter, Tab, or a click on another cell keeps the editor open, and the value does not commit. The message also shows in a line next to the cell. Escape cancels the edit and restores the old value.
- Soft rule (Notes): the value commits and the editor closes. The cell stays flagged. If you edit it again, the line shows next to the cell. A valid value clears the flag.
- Paste: copy a column of ages (some under 18) and paste it onto Age. Valid cells commit and invalid cells drop. Notes drops its invalid cells on paste too.
pnpm dlx shadcn@latest add @gridcn/data-grid-validation-demo
Make a schema async
Any Standard Schema whose validate returns a promise is async. The function form of validate stays synchronous. This column rejects a SKU that the server already holds:
import { z } from "zod";
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
async function isSkuFree(sku: string) {
const response = await fetch(`/api/sku/${encodeURIComponent(sku)}`);
return response.ok;
}
type Item = { id: string; sku: string };
const columns = defineColumns<Item>()([
{
id: "sku",
header: "SKU",
accessorKey: "sku",
validate: z.string().refine(isSkuFree, "Already in use"),
},
]);
export function Items({ items }: { items: Item[] }) {
return (
<DataGrid defaultData={items} columns={columns} getRowId={(i) => i.id} />
);
}A single edit
- The editor stays open while the promise is pending. The built-in editors set their input to
readOnly, neverdisabled, so Escape still cancels. - If the schema resolves with issues, the message shows like a sync rejection and editing continues.
- If the schema resolves with a value, the cell commits that value and then makes the move that Enter asked for.
- Escape, a newer commit, or an unmounted cell drops the pending result. A stale verdict never lands on a cell the user has left.
Paste, fill, and updateCells
Each of these paths holds the batch while the schema resolves, and so does import:
- The grid runs at most 32 validations at the same time. A paste of 10,000 cells makes 32 calls at a time.
- Nothing changes until every verdict is in. The accepted cells then commit together as one
onDataChangebatch. - A rejected cell drops, and the other cells still commit.
onValidationErrorreports the rejected cells. Its sources are paste, fill, Delete or Cut, find and replace,updateCells, and the toggle of anactivatecell. - A held batch drops when a sort or filter changes, or when a target row leaves the data.
- The import dialog keeps its Import button disabled while it validates.
While the schema runs, useDataGridGatePending() holds "validate" and the grid root carries data-gate-pending="validate". A newer paste replaces the held paste. At 200 ms per cell, 10,000 cells take about 60 seconds at 32 calls at a time. To check a large paste against a remote service, validate the whole block once in the processPaste override of Change copy and paste.
To skip validation for values that your server already checked, call actions.updateCells(patches, { skipValidation: true }).
Related
- Async schemas: the full contract
- Async gates example: a promise in
validateRow,processPaste, and the other gates - Server errors example: a rejection after the commit