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.
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
loadingis 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"whileloadingis true. - The screen reader progress element uses
labels.grid.loadingas 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
| Prop | Type | Default |
|---|---|---|
loading | boolean | false |
loadingState | ReactNode | LoadingStateRenderer | none |
emptyState | ReactNode | EmptyStateRenderer | labels.grid.emptyState, or labels.grid.noResults for "filtered" |
error | unknown | none |
onRetry | () => void | none |
errorState | ReactNode | ErrorStateRenderer | none |
Related
- Loading state example: the three states in a demo
- Labels and i18n: the texts of the empty, loading, and error states
- Server rows options:
onError,onLoaded, and the other hook options - DataGrid props: every prop of the grid