gridcn2.0.0
Support and upgrades

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

  1. Fetch the rows in a Server Component.
  2. Pass them as a prop to a client component.
  3. In the client component, pass them to data or defaultData.

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 locale prop on the server and in the browser. The grid default is "en-US". The number and date columns and the built-in labels read it. A column options.locale wins. In a custom cell type or label, pass a locale to Intl and toLocaleString.
  • Pin the text sort. The built-in text sorts use the locale prop, then "en-US", on the server and in the browser. Pass locale or sortLocale for another language, and pass the same value on both sides.
  • Read browser-only globals after mount. window, navigator, and localStorage do 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() or Math.random() differ on each side. Build them on the server and pass them as props, or build them in an effect.
  • Pass direction on 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.

On this page