Data Grid

Installation

$ npx @grampro/kit add DataGrid

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. The files land in component-lib/, or src/component-lib/ when your project has a src/ folder; pass --dest to put them somewhere else, and later installs follow the first. 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.