Data Grid

Installation

$ npx gbs-add-block@latest -a DataGrid -beta

The block copies the data-grid folder into your project, along with the small shared folder that every component imports. You own the code and can change it freely. There are no peer dependencies other than React.

Requirements

• React 19 and @types/react 19
• TypeScript target ES2022 or newer, with "jsx": "react-jsx"
• Browsers from 2024 or newer (the styles use light-dark(), :has() and the Popover API)

Import the stylesheet once, for example in your global CSS:

@import "../component-lib/gbs.css";

or in your root layout / entry file:

import "@/component-lib/gbs.css";

The DataGrid is a virtualized data grid for React 19 and Next.js. It renders only the rows and columns on screen, so it stays fast with 100,000+ rows. It supports sorting, typed column filters, global search, pagination, row selection, column resizing, reordering, pinning and hiding, inline editing with validation, CSV / Excel / PDF export, keyboard navigation, dark mode and right-to-left layouts. It works with data held in the browser (client mode) or fetched page by page from an API (server mode).

Demo

Quick Start

"use client";
 
import { createColumnHelper, DataGrid } from "@/component-lib/data-grid";
 
interface Employee {
  id: number;
  name: string;
  department: string;
  salary: number;
  startDate: string;
  active: boolean;
}
 
const col = createColumnHelper<Employee>();
 
// Define columns outside the component, or wrap them in useMemo.
const columns = [
  col.field("id", { header: "ID", type: "number", width: 80, pin: "left" }),
  col.field("name", { width: 200 }),
  col.field("department", {
    options: [
      { label: "Engineering", value: "Engineering" },
      { label: "Sales", value: "Sales" },
    ],
  }),
  col.field("salary", {
    type: "number",
    format: (value) => `$${value.toLocaleString()}`,
  }),
  col.field("startDate", { header: "Start date", type: "date" }),
  col.field("active", { type: "boolean" }),
];
 
export default function Employees({ data }: { data: Employee[] }) {
  return (
    <DataGrid
      data={data}
      columns={columns}
      getRowId="id"
      enableRowSelection
      height={600}
      onRowClick={(row) => console.log("Clicked", row)}
    />
  );
}

In this section

The Data Grid has more surface than one page can hold comfortably. This page covers installation, the props, and the things every grid needs; the rest is split by subject:

Props Table

Data

State

Features

Events

Layout and Appearance

Toolbar Options

Pass an object to toolbar to choose what the toolbar shows. Omitted options default to true.

<DataGrid
  data={data}
  columns={columns}
  toolbar={{
    density: false,
    end: <button onClick={openCreateDialog}>Add employee</button>,
  }}
/>

Keyboard Navigation

The grid follows the WAI-ARIA grid pattern. One cell is focusable at a time; Tab moves focus into and out of the grid.

Styling and Theming

The grid ships with default styles in styles.css. Rules ship unlayered, so a framework reset cannot strip them and a utility class passed through className still overrides them. Import the generated gbs.css once — see Theming.

<DataGrid
  data={data}
  columns={columns}
  className="rounded-xl shadow-sm"
  classNames={{
    headerCell: "uppercase tracking-wide",
    row: "hover:bg-indigo-50",
  }}
  getRowClassName={(row) => (row.active ? undefined : "opacity-60")}
/>

CSS variables

Override them on .dg-root, any ancestor, or through style.

Every --dg-* below first looks for the shared --gbs-* variable of the same name, so one palette on :root themes the grid and every other component together:

:root {
  --gbs-accent: #7c3aed;
  --gbs-radius: 12px;
  --gbs-font-size: 14px;
}

Set --dg-* when you want to change the grid alone, or to override a shared value for it:

.dg-root {
  --dg-accent: #7c3aed;
  --dg-radius: 12px;
  --dg-font-size: 14px;
}

Dark mode

Colors follow the page's color-scheme. To force a scheme, put class="dark" or data-theme="dark" (or "light") on an ancestor such as <html>.

Data attributes

Use these to style states, for example .dg-row[data-selected] or Tailwind's data-[active]:.

Locale Text

Override any text with localeText. Dates and numbers use the locale prop.

<DataGrid
  locale="de-DE"
  localeText={{
    searchPlaceholder: "Suchen…",
    noRows: "Keine Daten",
    selected: (count) => `${count} ausgewählt`,
    pageRange: (from, to, total) => `${from}–${to} von ${total}`,
  }}
/>

Next.js

• Every component file starts with "use client", so DataGrid works in the App Router.
• Column definitions contain functions, which can't be passed from a Server Component to a Client Component. Define columns in a client module (a file with "use client") and render the grid there.
• A Server Component can fetch the first page and pass data, rowCount and initialState (plain values) to that client component.

Migrating from the Previous Grid

Notes

• Rows have a fixed height (set by density or rowHeight). Variable-height rows are not supported.
• Grouping, tree data and pivoting are not supported yet.
• Client mode handles 100,000+ rows. For millions of rows, use server mode.