Support and upgrades
Adopt the grid in an existing table
Replace one table of an existing app with the grid, keep your fetch and your state, and map each column to a ColumnDef.
The grid takes an array of rows and a list of column definitions. It has no table library underneath and no table instance to share. You replace one table at a time, and the other tables of the app keep running.
Before you start
- Your project needs React 19, Tailwind CSS 4, and shadcn/ui set up with
npx shadcn init. See Install gridcn. - The core installs four npm packages:
zustand,use-sync-external-store,lucide-react, and@base-ui/react. It adds no table library. - The CLI writes the grid to
components/data-grid/and adds the shadcn/ui components that the grid uses. If a component file differs from yours, the CLI asks before it overwrites it.
Steps
- Run
npx shadcn add @gridcn/data-grid. - Keep the code that loads your rows. Pass the rows as
dataand your setter asonDataChange. If a row has noidfield, passgetRowId. - Map each column of the old table to a
ColumnDef, as the table below shows. - If your page holds the sort or the filters, pass them as
sortStateandfilterStatewithonSortChangeandonFilterChange. If your server sorts and filters, also setsortMode="server"andfilterMode="server".totalRowCountsets both to"server"by default. For a server table,useDataGridServerRowswires all of it. - Give the grid a fixed height, for example
className="h-96". - After the last page moves to the grid, delete the old table component.
Map the columns
| Old column setting | ColumnDef field |
|---|---|
| The field that the column shows | accessorKey |
| A value that the column computes | accessorFn: (row) => value |
| The heading | header |
| A number, date, checkbox, or choice column | type: "number", "date", "checkbox", or "select" with options.choices |
| A custom cell render | renderCell. See Display override. |
| A fixed width | width in pixels |
Every column needs a unique id. defineColumns<Row>() checks each accessorKey against your row type. This sample keeps the fetch, the sort state, and the filter state of the page:
"use client";
import { useState } from "react";
import {
DataGrid,
defineColumns,
type FilterNode,
type SortSpec,
} from "@/components/data-grid/data-grid";
type Order = { id: string; customer: string; total: number };
const columns = defineColumns<Order>()([
{ id: "customer", header: "Customer", accessorKey: "customer", type: "text" },
{ id: "total", header: "Total", accessorKey: "total", type: "number" },
] as const);
export function OrdersTable({ orders }: { orders: Order[] }) {
const [rows, setRows] = useState<readonly Order[]>(orders);
const [sorts, setSorts] = useState<SortSpec[]>([]);
const [filters, setFilters] = useState<FilterNode[]>([]);
return (
<DataGrid
data={rows}
onDataChange={setRows}
columns={columns}
sortState={sorts}
onSortChange={setSorts}
filterState={filters}
onFilterChange={setFilters}
className="h-96"
/>
);
}Result
The new grid shows the same rows and columns as the old table, and your state still drives the sort and the filters. The other tables of the app run as before.
Related
- Define columns: the column settings step by step
- ColumnDef: every column field
- Event shapes: controlled props and their callbacks
- Load server rows: move a server table to the grid
- Upgrade gridcn: reinstall the files after a release