gridcn2.0.0
Server path

Plan server saves

Step 3 of 5

Choose how onSave answers your server, from a full revert to a refetch, a per-row refusal, or an error on one cell, and wire the first save.

Before you start, load server rows. An edit already appears in the grid before your server hears about it. onSave sends the edit to your server and tells the grid what the server answered. This step picks the answer.

Choose the answer

Find the first line that matches your server:

If your serverThen onSaveTask
Accepts or refuses a whole changeReturns the request promise. A rejection reverts the change.Revert or refetch after a save
Recomputes values after a writeWaits for the request. The hook then refreshes the rows.Revert or refetch after a save
Refuses some rows of a changeResolves with { rejected }. The grid reverts only those rows.Handle refused saves
Rejects one field that the user can fixResolves normally and calls setCellErrors.Show errors on cells

An onSave that returns no promise and does not throw cannot revert. The grid tracks a save only while its promise is pending. A thrown error counts as a refusal of the whole change.

Wire the first save

This grid imports columns and Order from orders.ts and loadPage from api.ts, both from Load server rows. It sends each change to an API, and the hook fetches the page again after the saves settle. If the request fails, the thrown error reverts the change:

"use client";

import { DataGrid } from "@/components/data-grid/data-grid";
import {
  DataGridPaginationBar,
} from "@/components/data-grid-pagination/data-grid-pagination";
import {
  useDataGridServerRows,
} from "@/components/data-grid-server/data-grid-server";
import { columns, type Order } from "./orders";
import { loadPage, sendChange } from "./api";

export function OrdersGrid() {
  const server = useDataGridServerRows<Order>({
    fetchRows: loadPage,
    onSave: sendChange,
  });

  return (
    <>
      <DataGrid {...server.gridProps} columns={columns} className="h-96" />
      <DataGridPaginationBar {...server.pager} />
    </>
  );
}

change.ops holds one operation (ops) for each touched row. Key each request by rowId, because a sort or a filter moves the view index.

Where onSave goes:

  • Pass onSave to the hook. The hook runs it and then refreshes the rows by the refreshAfterSave policy.
  • An onSave on DataGrid after {...server.gridProps} replaces the one of the hook. Then refreshAfterSave stops, and the hook warns in development.

The save status of a row:

  • "saving" while the promise is pending. A refresh keeps the local value of a saving row.
  • Cleared after the promise resolves.
  • "failed" after a refusal.

The refreshAfterSave option of the hook defaults to "settled". When every save in flight has settled, the hook calls refresh() once. If a save is still in flight 10 seconds after the first one started, the hook refreshes for the saves that settled by then.

The hook skips that refresh when no save has settled. When every save failed, no refresh runs. An onSave that returns no promise never triggers a refresh, so call server.refresh() yourself. refreshAfterSave: false turns the refresh off. See Save options for the other policies.

onSave never receives the revert, which has the source "rollback". It never receives a server push, which has the source "stream".

Result

An edit shows at once. A refused save reverts the edit. An accepted save stays, and the refresh brings in the values that the server computed.

Next: Handle failures.

On this page