gridcn2.0.0
Theme, style, and language

Loading state

Show a skeleton or a progress bar while data loads, replace it with your own display, and show a failed load with a retry button.

A grid with zero rows shows the empty state, which reads as a query without results. While a request runs, that message is wrong. Set loading and the grid shows that data is on the way. The flag is presentational. It does not fetch anything.

Toggle both switches: Loading with no rows shows a viewport-filling skeleton, Loading with rows present shows a slim bar under the header instead, and rows-off + loading-off is the ordinary empty state.

Name
Email
Role
Score
Silent Tiger
user0@example.com
Viewer
4
Quick Lion
user1@example.com
Viewer
89
Swift Wolf
user2@example.com
Manager
80
Eager Lion
user3@example.com
User
51
Eager Tiger
user4@example.com
Viewer
83
Silent Wolf
user5@example.com
User
15
Swift Lion
user6@example.com
Viewer
62
Eager Lion
user7@example.com
Manager
42
Eager Eagle
user8@example.com
Editor
35
Bold Tiger
user9@example.com
Editor
52

Loading flag

Pass loading to DataGrid or DataGridRoot:

"use client";

import { useState } from "react";
import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";

type Row = { id: string; name: string };

const columns = defineColumns<Row>()([
  { id: "name", header: "Name", accessorKey: "name" },
]);

export function LoadingGrid({ rows }: { rows: Row[] }) {
  const [loading, setLoading] = useState(true);
  return (
    <>
      <button onClick={() => setLoading(false)}>Loaded</button>
      <DataGrid
        className="h-80"
        data={rows}
        readOnly
        columns={columns}
        loading={loading}
      />
    </>
  );
}
  • With zero rows, a skeleton fills the viewport. The empty state does not show while loading is true.
  • With rows present, such as a background refresh, the rows stay visible. A slim indeterminate bar appears under the header.
  • The grid root has aria-busy="true" while loading is true.
  • The screen reader progress element uses labels.grid.loading as its label. The skeleton and the bar are hidden from assistive technology.
  • With prefers-reduced-motion, the skeleton does not pulse and the bar does not sweep.

--grid-loading-sweep-duration sets the duration of the sweep. The default is 1.2s.

Replace the display

loadingState replaces the skeleton and the bar. It takes a node, or a function that receives { reason }. reason is "no-data" for zero rows and "rows-present" otherwise. The grid renders the result under the header at full width. The node owns its accessibility:

"use client";

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";

type Row = { id: string; name: string };

const columns = defineColumns<Row>()([
  { id: "name", header: "Name", accessorKey: "name" },
]);

type Props = { rows: Row[]; loading: boolean };

export function FetchingGrid({ rows, loading }: Props) {
  return (
    <DataGrid
      className="h-80"
      data={rows}
      columns={columns}
      loading={loading}
      loadingState={({ reason }) => (
        <p className="p-4 text-sm">
          {reason === "no-data" ? "Fetching rows…" : "Refreshing…"}
        </p>
      )}
    />
  );
}

Empty state

A grid with no rows in view shows the empty state. The text is labels.grid.emptyState ("No rows"). When a filter or a server search leaves no row, the text is labels.grid.noResults ("No results"). To change only the words, set those labels. See Labels and i18n.

emptyState replaces the message. It takes a node, or a function that receives { reason }. reason is "filtered" when a filter or a server search leaves no row, and "no-data" otherwise:

"use client";

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";

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

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

export function OrdersGrid({ orders }: { orders: Order[] }) {
  return (
    <DataGrid
      className="h-80"
      data={orders}
      columns={columns}
      emptyState={({ reason }) =>
        reason === "filtered" ? "No orders match the filter." : "No orders yet."
      }
    />
  );
}

Error state

A failed load needs its own message. Any error value except undefined and null shows it. With zero rows, the grid centers a message with a Retry button. With rows present, a slim alert bar appears under the header and the rows stay. The text comes from labels.grid.errorState, and the built-in display never shows the error value.

Pressing Retry runs onRetry. If you omit onRetry, the button stays hidden. errorState replaces the display with a node, or with a function that receives { error, retry }. retry is undefined without onRetry. This grid shows its own message and a Retry button:

"use client";

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";

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

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

export function OrdersGrid({
  orders,
  error,
  reload,
}: {
  orders: Order[];
  error: unknown;
  reload: () => void;
}) {
  return (
    <DataGrid
      className="h-80"
      data={orders}
      columns={columns}
      error={error}
      onRetry={reload}
      errorState={({ retry }) => (
        <div className="p-4 text-sm">
          Orders did not load.
          {retry && <button onClick={retry}>Try again</button>}
        </div>
      )}
    />
  );
}

Server mode

The hooks for server rows return loading, error, and onRetry in gridProps. Spread gridProps on DataGrid and the states work with no more code. In the split form, spread providerProps on DataGridProvider and rootProps on DataGridRoot. loading is true while a request of the current spec runs. error holds the failure of that request, and onRetry repeats it.

In scroll mode, loading is true while any block request runs. Rows that are not loaded yet also show a skeleton in their cells. onError and onLoaded of the hook fire after a request fails or lands. Server rows options lists them.

Options

PropTypeDefault
loadingbooleanfalse
loadingStateReactNode | LoadingStateRenderernone
emptyStateReactNode | EmptyStateRendererlabels.grid.emptyState, or labels.grid.noResults for "filtered"
errorunknownnone
onRetry() => voidnone
errorStateReactNode | ErrorStateRenderernone

On this page