Render the grid on the server
See what the server HTML of a grid holds, and keep the first browser render equal to it, so that hydration succeeds.
In the Next.js App Router, the server renders each client component to HTML, and the browser hydrates that HTML. If the first browser render differs from the server HTML, hydration fails. This page lists what the grid renders on the server and the rules that keep both renders equal.
What the server renders
data-grid.tsx starts with "use client", so render the grid from a client component. The server HTML holds:
- the header row and the column group headers
- every pinned column and the first 20 other columns
- the first 30 rows of the view, sorted and filtered as in the first render (see Pin the text sort below)
- the row bands, such as pinned totals rows, with their heights
The server cannot know the height of the grid, so it renders a fixed preview. After hydration, the grid measures itself and renders the visible rows plus the overscan. Serve the page with compression.
A grid that mounts in the browser only, for example after a client navigation, renders no data cell in its first commit. Its rows are in the DOM by the first frame.
Render rows on the server
- Fetch the rows in a Server Component.
- Pass them as a prop to a client component.
- In the client component, pass them to
dataordefaultData.
orders-db.ts stands for your data access:
type Order = { id: string; customer: string; total: number };
export async function loadOrders(): Promise<Order[]> {
return [{ id: "1", customer: "Ada", total: 12 }];
}This page loads the orders on the server:
import { OrdersGrid } from "./orders-grid";
import { loadOrders } from "./orders-db";
export default async function OrdersPage() {
const orders = await loadOrders();
return <OrdersGrid orders={orders} />;
}orders-grid.tsx renders them:
"use client";
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";
type Order = { id: string; customer: string; total: number };
const columns = defineColumns<Order>()([
{ id: "customer", header: "Customer", accessorKey: "customer" },
{ id: "total", header: "Total", accessorKey: "total", type: "number" },
]);
export function OrdersGrid({ orders }: { orders: Order[] }) {
return (
<DataGrid
defaultData={orders}
columns={columns}
className="h-96"
/>
);
}With useDataGridServerRows in pages mode, pass the first page as initialAnswer, for example from a Server Component. The server HTML then holds the rows, and the hook sends no request until the state changes. In scroll mode, initialAnswer is block 0, rows [0, blockSize). The hook sends no request for block 0, and it fetches block 1 when the rendered rows reach it.
Keep the first render equal
- Pass the same
localeprop on the server and in the browser. The grid default is"en-US". Thenumberanddatecolumns and the built-in labels read it. A columnoptions.localewins. In a custom cell type or label, pass a locale toIntlandtoLocaleString. - Pin the text sort. The built-in text sorts use the
localeprop, then"en-US", on the server and in the browser. PasslocaleorsortLocalefor another language, and pass the same value on both sides. - Read browser-only globals after mount.
window,navigator, andlocalStoragedo not exist on the server. Read them in an effect and set state. Column visibility loads a saved layout this way. - Make the rows once. Rows built in render with
Date.now()orMath.random()differ on each side. Build them on the server and pass them as props, or build them in an effect. - Pass
directionon a right-to-left page. Without the prop, the server HTML is left-to-right, and the grid reads the inherited direction at mount. See RTL layout. - Render the same text in a plugin. The grid renders row bands on the server. See Server rendering of plugins.
BindingChips of data-grid-keybindings renders key names as words on the server. On macOS, iOS, and iPadOS it switches to glyphs after hydration. This change happens after hydration, so it causes no mismatch.
Result: the browser hydrates the server HTML without a hydration warning in the console.
Related
- Install gridcn: the
"use client"rule - Browser and framework support
- Write a cell type: pin the locale
- Bundle size