Server errors example
Mark a cell with the message of a server rejection after the value committed, and see the error clear when the user edits the cell.
A validate rule runs before a value commits. A server can still refuse a value after it committed, for example with a 422 that names the field. actions.setCellErrors marks that cell. In this grid, the onSave handler calls a fake saveOrders that rejects a Quantity above 100 after about 600 ms. Set Quantity to 150 and press Enter. The cell gets an error ring. Hover the cell to read the message.
Set a Quantity above 100 and press Enter: the fake server rejects it after ~600ms and the cell is marked with a red ring — hover it to read the message.
pnpm dlx shadcn@latest add @gridcn/data-grid-cell-errors-demo
How the demo is wired
onSave sends change.ops to the server. When the call fails, its catch block maps each failure to a { rowId, columnId, message } entry and calls setCellErrors. The rejection arrives long after the grid mounted, so the handler reaches the actions through a ref:
import { useRef } from "react";
import {
DataGrid,
defineColumns,
type CellErrorEntry,
type DataChange,
type DataGridApi,
} from "@/components/data-grid/data-grid";
type Order = { id: string; item: string; quantity: number };
const columns = defineColumns<Order>()([
{ id: "item", header: "Item", accessorKey: "item" },
{
id: "quantity",
header: "Quantity",
accessorKey: "quantity",
type: "number",
},
]);
async function saveOrders(ops: DataChange<Order>["ops"]): Promise<void> {
const response = await fetch("/api/orders", {
method: "POST",
body: JSON.stringify(ops),
});
if (!response.ok) throw new Error(await response.text());
}
function parseFieldErrors(error: unknown): CellErrorEntry[] {
const rowId = "1";
const message = error instanceof Error ? error.message : "Refused";
return [{ rowId, columnId: "quantity", message }];
}
export function OrdersGrid({ orders }: { orders: Order[] }) {
const gridRef = useRef<DataGridApi<Order>>(null);
async function handleSave(change: DataChange<Order>) {
try {
await saveOrders(change.ops);
} catch (error) {
gridRef.current?.actions.setCellErrors(parseFieldErrors(error));
}
}
return (
<DataGrid
ref={gridRef}
defaultData={orders}
columns={columns}
getRowId={(row) => row.id}
onSave={handleSave}
/>
);
}saveOrders rejects when the server refuses a value, and parseFieldErrors turns that error into the entries to mark. The stubs in the sample mark one fixed cell. Read the row id and the column id from your server answer.
Mark the cell or revert the value
Because the catch block returns normally, the onSave promise resolves. The grid keeps the value and setCellErrors marks the cell. If onSave rejects or returns a refusal in a SaveAck, the grid reverts the value instead. See Handle refused saves.
What to expect
setCellErrorsmerges its entries per cell. Calling it with an empty list does nothing.- A marked cell gets
aria-invalidand the same ring and tint as avalidaterejection. Opening the cell for editing shows the message. - When any write path (an edit, a paste, a fill, or
updateCells) commits a new value to a marked cell, its error clears. The server can mark the cell again if the new value is still wrong. clearCellErrors()clears every error.clearCellErrors(targets)clears the cells named by{ rowId, columnId }targets.useDataGridCellErrors()returns the map of all messages. The demo bar reads its size and offers a Clear all button.
Cell errors are not edits
setCellErrors and clearCellErrors never touch data. They fire no onDataChange. The history add-on never records them. A server error is a mark on a cell, not an edit of the user.
Related
- Show errors on cells: the task, with the full list of what clears an error
- Validation example: the rules that run before the commit
- Cross-field validation example: a row rule that reuses the same marks
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.
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.