gridcn2.0.0
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

  1. Run npx shadcn add @gridcn/data-grid.
  2. Keep the code that loads your rows. Pass the rows as data and your setter as onDataChange. If a row has no id field, pass getRowId.
  3. Map each column of the old table to a ColumnDef, as the table below shows.
  4. If your page holds the sort or the filters, pass them as sortState and filterState with onSortChange and onFilterChange. If your server sorts and filters, also set sortMode="server" and filterMode="server". totalRowCount sets both to "server" by default. For a server table, useDataGridServerRows wires all of it.
  5. Give the grid a fixed height, for example className="h-96".
  6. After the last page moves to the grid, delete the old table component.

Map the columns

Old column settingColumnDef field
The field that the column showsaccessorKey
A value that the column computesaccessorFn: (row) => value
The headingheader
A number, date, checkbox, or choice columntype: "number", "date", "checkbox", or "select" with options.choices
A custom cell renderrenderCell. See Display override.
A fixed widthwidth 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.

On this page