gridcn2.0.0
Add-on optionsServer

Server rows options

Look up the options, request, answer, and result of useDataGridServerRows in pages mode and scroll mode, and the options of a server pager.

useDataGridServerRows owns the sort, filter, search text, and rows of one server source. You write fetchRows. The hook calls it, aborts a request that a newer one replaces, and keeps the last good rows on screen. mode picks how rows reach the grid. The steps and the contract are on Server rows contract.

SymbolPurposeGuide
Pages modeFetches one page for each stateLoad rows by page
Scroll modeFetches blocks as the rendered rows moveLoad rows while scrolling
useDataGridServerPagerBuilds the pager for rows you fetch yourselfLoad rows by page
onSave and refreshAfterSaveSends a change to your server and refreshes after itSave edits
ServerRowsRequestThe request that fetchRows receivesServer rows contract
ServerRowsAnswerThe answer that fetchRows returnsServer rows contract

Both modes set sortMode and filterMode to "server". To sort or filter the loaded rows in the browser, set sortMode="client" or filterMode="client".

A handler or plugins prop after the gridProps spread joins the hook wiring. onDataChange, onSortChange, onFilterChange, onSearchTextChange, and onRenderedRowsChange run next to the hook's handler. plugins mount after the refresh guard. An onSave prop runs in place of the onSave option, and the hook still refreshes after it settles.

Pages mode

The default mode fetches one page for each state. If the sort, the filter, the search text, or the page size changes, the grid returns to page 1.

Prop

Type

The hook keeps page between 1 and the last page of 10,000,000 rows at the current page size. A page that is not a positive integer becomes 1. At mount, it waits one timer tick before the first request, so a spec that your URL state restores replaces that request before it leaves. If onError or onLoaded throws, the hook logs the error and carries on.

initialAnswer is the answer for the first state. The hook shows it without a request, so the server HTML holds the rows. onLoaded does not fire for it, and the next state fetches as usual. In scroll mode, it is the answer of block 0 for the first spec. Rows past blockSize are cut, and another first spec drops it.

Result

Both modes return the request state as DataSourceState: status, loading, error, retry, refresh, and reshape.

Prop

Type

Spread gridProps onto DataGrid. For a composed layout, spread providerProps onto DataGridProvider and rootProps onto DataGridRoot.

providerProps holds:

Prop

Type

rootProps holds:

Prop

Type

Pager options

pager in pages mode comes from useDataGridServerPager. If you fetch rows without useDataGridServerRows, call that hook yourself. It returns { pager, gridProps }: spread gridProps onto the grid for totalRowCount and for a DataGridPaginationBar with no props. Pass page, pageSize, totalRowCount, and onPageChange, and fetch each page yourself. If the server sends no count, pass totalRowCount: null and hasMore.

Prop

Type

If page is outside the page range, the hook calls onPageChange once with the clamped page. It skips this while totalRowCount is 0, so a deep link survives until the first count arrives. If you pass no onPageSizeChange, the bar hides the page-size select. DataGridPaginationControls is the result. See Client pagination options.

Without a total

A server that sends no count answers totalRowCount: null and hasMore. The pager then reports totalRowCount: null:

  • The footer shows "Page 3" in place of a range.
  • Next stays enabled while hasMore is true, and Last stays disabled.
  • The page count is the current page, plus 1 while hasMore is true.
  • useDataGridServerPager raises a page below 1 to 1. It caps the page at the last page of 10,000,000 rows. The pager itself leaves the upper end open when the count is unknown.

Scroll mode

Set mode: "scroll" to fetch fixed-size blocks as the rendered rows move. The first answer picks the fetch order. A totalRowCount without nextCursor gives random access. A nextCursor, or neither, gives a sequential source.

Set source: "random" or source: "sequential" to fix the order. A random source that answers without totalRowCount warns in development.

getRowId is optional in both modes. It defaults to the id field of the row, the same default as DataGridProvider. A row without a string or number id throws.

Scroll options

Prop

Type

Fetch limits

OptionDefaultEffect
loadDelayMs100Milliseconds a block stays in the wanted range before its request starts. At most 2000. 0 starts at once.
maxConcurrentFetches3Most block requests in flight on a random access source. At most 16.
maxLoadedRows10000Most rows kept loaded. On a random access source, old blocks unload past it. A sequential source unloads the blocks furthest from the rendered rows and reloads them from their stored cursor. A value below blockSize counts as blockSize. Infinity keeps every row.
revalidateIntervalMsoffMilliseconds between timed refresh() calls while the page is visible. At least 1000. A sequential source skips a tick while the rendered rows plus overscan end beyond 10 blocks.
reshapeDelayMs1000 with a sort or a filter, else offMilliseconds after a push marked a row stale before one refresh(). At least 250. false turns it off. A sequential source skips it while the rendered rows plus overscan end beyond 10 blocks.

The limits and the timers are on Tune row retention.

Scroll result

Prop

Type

In scroll mode, providerProps holds:

Prop

Type

Save options

Both modes take onSave and refreshAfterSave. gridProps.onSave runs your handler and then refreshes by the policy:

OptionDefaultEffect
onSavenoneSends a change to your server. Behaves as the DataGridProvider prop of the same name.
refreshAfterSave"settled"The refresh policy after a save. See the list below.
  • "settled" refreshes once after every save in flight has settled, or after 10 seconds when at least one save has settled by then. After the 10 seconds, each save still in flight refreshes when it settles.
  • "each" refreshes after saves settle, without waiting for the saves still in flight.
  • false never refreshes.
  • A function of the save report returns whether to refresh. It runs once after every save in flight has settled, or after the same 10 seconds.
  • A sequential source skips the refresh while the rendered rows plus overscan end beyond 10 blocks. server.canRevalidate() returns false then, and the hook warns once in development. Call server.refresh() there.
  • Only an onSave that returns a promise triggers a refresh.
  • When every save failed, no refresh runs.

refresh() stays available. See Save edits.

Request

fetchRows receives the same request in both modes. Pages mode adds the page address.

Both modes send a ServerRowsRequest:

Prop

Type

Pages mode sends a ServerRowsPageRequest, which adds:

Prop

Type

spec holds sorts, filters, and searchText. Treat it as untrusted input in your backend.

Answer

Prop

Type

The hook checks every answer before it uses it:

  • An answer without a rows array fails the request and sets error.
  • The hook drops rows beyond end - start, and development builds warn.
  • A totalRowCount that is not a non-negative integer counts as unknown. A count above 10,000,000 clamps to 10,000,000. A browser scrolls fewer rows than that in scroll mode: see Row limits.
  • A repeated row id keeps its first row, and development builds warn once. In random access, the later copy leaves an empty slot that shows as a skeleton row. Pages mode and a sequential source drop the later copy, so the page holds one row fewer. Make the sort total, with the row id as the last sort key.
  • An answer with hasNextPage, or with total and no totalRowCount, warns in development. The hook reads only totalRowCount and hasMore.

Example

This sample loads orders by page from an API:

import { DataGrid, defineColumns } 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";

type Order = { id: string; customer: string };

const columns = defineColumns<Order>()([
  { id: "customer", header: "Customer", accessorKey: "customer" },
]);

export function OrdersGrid() {
  const server = useDataGridServerRows<Order>({
    defaultPageSize: 25,
    fetchRows: async ({ start, end, spec, signal }) => {
      const response = await fetch("/api/orders", {
        method: "POST",
        body: JSON.stringify({ start, end, spec }),
        signal,
      });
      const { rows, total } = await response.json();
      return { rows, totalRowCount: total };
    },
  });
  return (
    <>
      <DataGrid {...server.gridProps} columns={columns} />
      <DataGridPaginationBar {...server.pager} />
    </>
  );
}

Your API reads start and end as the row range and returns the rows with the count of the filtered result.

Save policy types

  • SaveRefreshPolicy is the value of refreshAfterSave: false, "each", "settled", or a function of a SaveRefreshReport.
  • SaveRefreshReport describes the saves of one batch. It holds the saved, rejected, and failed counts. It holds the changes of those saves, oldest first, at most 100. It holds pending, the saves still in flight. pending is above 0 only when the 10 second wait forced the decision.

On this page