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.
| Symbol | Purpose | Guide |
|---|---|---|
| Pages mode | Fetches one page for each state | Load rows by page |
| Scroll mode | Fetches blocks as the rendered rows move | Load rows while scrolling |
useDataGridServerPager | Builds the pager for rows you fetch yourself | Load rows by page |
onSave and refreshAfterSave | Sends a change to your server and refreshes after it | Save edits |
ServerRowsRequest | The request that fetchRows receives | Server rows contract |
ServerRowsAnswer | The answer that fetchRows returns | Server 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
hasMoreistrue, and Last stays disabled. - The page count is the current page, plus 1 while
hasMoreistrue. useDataGridServerPagerraises 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
| Option | Default | Effect |
|---|---|---|
loadDelayMs | 100 | Milliseconds a block stays in the wanted range before its request starts. At most 2000. 0 starts at once. |
maxConcurrentFetches | 3 | Most block requests in flight on a random access source. At most 16. |
maxLoadedRows | 10000 | Most 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. |
revalidateIntervalMs | off | Milliseconds 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. |
reshapeDelayMs | 1000 with a sort or a filter, else off | Milliseconds 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:
| Option | Default | Effect |
|---|---|---|
onSave | none | Sends 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.falsenever 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
overscanend beyond 10 blocks.server.canRevalidate()returnsfalsethen, and the hook warns once in development. Callserver.refresh()there. - Only an
onSavethat 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
rowsarray fails the request and setserror. - The hook drops rows beyond
end - start, and development builds warn. - A
totalRowCountthat 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 withtotaland nototalRowCount, warns in development. The hook reads onlytotalRowCountandhasMore.
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
SaveRefreshPolicyis the value ofrefreshAfterSave:false,"each","settled", or a function of aSaveRefreshReport.SaveRefreshReportdescribes the saves of one batch. It holds thesaved,rejected, andfailedcounts. It holds thechangesof those saves, oldest first, at most 100. It holdspending, the saves still in flight.pendingis above 0 only when the 10 second wait forced the decision.
Related
- Server rows contract: what the grid sends and what your backend returns.
- Load rows by page: the task for pages mode.
- Load rows while scrolling: the task path for scroll mode.
- Client pagination options: the pager and the footer.