gridcn2.0.0
Validation examples

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.

Item
Quantity
Status
Widget
12
ok
Gadget
40
ok
Gizmo
8
ok
Doohickey
25
ok
Thingamajig
60
ok
Server errors: 0
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

  • setCellErrors merges its entries per cell. Calling it with an empty list does nothing.
  • A marked cell gets aria-invalid and the same ring and tint as a validate rejection. 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.

On this page