gridcn

Range selection, spreadsheet clipboard, typed cell editors, validation, and virtualized rendering at 100k+ rows. The code lands in your project, so you own every line. The core grid is the engine; every other feature is an add-on that depends only on the core.

Features

• Range selection. Anchor plus rectangular range, ctrl-click multi-range, row and column selection, and keyboard extension (Shift+Arrow, Shift+Ctrl+Arrow, Ctrl+A).
• Spreadsheet clipboard. Native copy, cut, and paste in TSV and HTML table formats, to and from Excel, Google Sheets, Apple Numbers, and LibreOffice.
• Typed editing. Text, long text, number, checkbox, date, select, and safe-link (url) cells, plus custom cell types. The fill-handle add-on adds series fill.
• Typed columns. defineColumns<TData>() infers value types and per-cell-type options from your data shape. A typo in an accessor key is a compile error.
• Validation. A function or any Standard Schema library (Zod, Valibot, ArkType). Sync and async, on single edits and on bulk paste, fill, and import.
• Server errors. setCellErrors paints an API rejection on the exact cell. The error clears when the user commits a fix.
• Streaming updates. updateCells applies live value patches without a full re-render. An incremental sort keeps sorted grids correct and fast at 100k rows.
• Virtualization. CSS Grid with virtualized row rendering. A real-browser test suite enforces the no-blank-rows guarantee at 100k rows.
• Row operations. Insert above or below, duplicate, and delete, each with a default key binding. Insert and duplicate need the createRow / duplicateRow props; the data-grid-context-menu add-on adds the menu entries.
• Touch. A tap selects, a double-tap edits, a long-press opens the context menu, and selection handles extend a range. Touch targets grow under a coarse pointer.
• Column groups. The columnGroups prop adds header rows that group columns, which reorder and select together.
• Global shortcuts. The opt-in DataGridGlobalShortcuts layer (inside DataGridRoot) keeps key bindings active while focus is outside the grid. Undo and redo by default; per-action flags enable more.
• Controlled or uncontrolled. Data, sort, and filter are uncontrolled by default. Pass data, sortState, or filterState with the matching on*Change callback to control them. Selection and column layout stay store-owned; onSelectionChange and onColumnLayoutChange observe them.
• RTL and i18n. A direction prop (or dir="rtl" on the page) mirrors layout, pinning, pointer math, and keyboard semantics. Every user-facing string lives in one typed labels object with English defaults.
• Your theme. Styled through your shadcn CSS tokens plus a few --grid-* variables, for example --grid-column-border. See the styling guide.
• Plugins. A single plugins prop mounts add-ons and your own overlays, row bands, observers, commands, and keymap entries. See the plugin guide.
• Accessibility. WAI-ARIA grid roles, roving tabindex, and live regions. axe-core reports zero violations on the test fixture in Chromium. No screen reader and no WCAG conformance audit has been run yet; see the accessibility page.

Install

npx shadcn add @gridcn/data-grid

The CLI resolves the @gridcn registry from the hosted site, so there is no setup step. Install add-ons the same way, for example npx shadcn add @gridcn/data-grid-toolbar.

To pin a tag, branch, or commit, use the GitHub registry path:

npx shadcn add DammersCode/gridcn/data-grid#v1.0.0

The ref applies to the item you name only. The CLI resolves its registryDependencies without the ref, so a pinned add-on still installs the core from the default branch. To pin the whole install, install the core with the same ref first. An @gridcn add-on install fetches the core through git ls-remote and raw.githubusercontent.com, so it needs git and access to GitHub.

The installation docs cover prerequisites, framework notes, and known problems.

Example

This file renders an editable grid. defaultData seeds the grid once; after that, the grid owns the rows, so you need no state of your own:

"use client";

import { DataGrid, defineColumns } from "@/components/data-grid/data-grid";

type Person = { id: string; name: string; age: number; active: boolean };

const columns = defineColumns<Person>()([
  { id: "name", header: "Name", accessorKey: "name", type: "text", width: 160 },
  { id: "age", header: "Age", accessorKey: "age", type: "number", width: 90 },
  { id: "active", header: "Active", accessorKey: "active", type: "checkbox", width: 90 },
] as const);

const initialRows: Person[] = [
  { id: "1", name: "Ada Lovelace", age: 28, active: true },
  { id: "2", name: "Grace Hopper", age: 34, active: true },
];

export function PeopleGrid() {
  return (
    <DataGrid
      defaultData={initialRows}
      columns={columns}
      getRowId={(row) => row.id}
      className="h-[400px]"
    />
  );
}

The quick start walks through the same example and the controlled variant.

Add-ons

Each add-on is a separate registry item that depends only on the core data-grid:

Agent skills

npx skills add DammersCode/gridcn

Five skills teach Claude Code, Cursor, Codex, and other coding agents the procedures and silent traps of gridcn: performance audits, custom cell types, data sources, add-on wiring, and upgrades. The Agent Skills page describes each one.

Updating

Re-run the install command, for example npx shadcn add @gridcn/data-grid (or the GitHub path for pinned refs). The CLI shows a diff and asks before it overwrites files that you edited.

Contributing

CONTRIBUTING.md has the repository structure rules. DEVELOPMENT.md covers local development, the test gates, benchmarking, the registry build, and consumer-install troubleshooting. The docs site source is in content/docs/.

Credits

gridcn builds on and learns from several open-source projects. Thank you.

• shadcn/ui: the registry distribution system (registry.json, the shadcn CLI) that ships gridcn, and the UI primitives (button, input, select, popover, dropdown-menu, context-menu, calendar, and more) that its chrome composes.
• Base UI: the headless, accessible primitives under the shadcn components (@base-ui/react).
• diceui (MIT, (c) 2024 Sadman Sakib): the toolbar, filter, and sort-list UX patterns and the FPS meter are adapted from it.
• tablecn (MIT, (c) Sadman Sakib): the aligned-row layout of the filter and sort popovers, and the join-column pattern, are adapted from it.
• @dnd-kit: drag-to-reorder in the filter and sort-list popovers (data-grid-toolbar, data-grid-sort-list). Column reorder in the core grid uses native pointer events, with no dependency.
• lucide (ISC): the icons of the grid's chrome: menus, sort indicators, pagination, markers, and dialogs.
• PapaParse (MIT): the CSV parsing behind the data-grid-io import.
• nuqs (MIT): the searchParams-based URL sync under data-grid-url-state.
• Standard Schema (MIT): the vendor-neutral validation interface that a cell's validate option accepts (Zod, Valibot, and more).
• Zustand: the state store under the core grid and every add-on with its own local store (for example, data-grid-presence).
• Fumadocs: the documentation site: content layer, search, and page layout.

License

Apache License 2.0 © DammersCode. Behavior specs from other data grids are inspiration only, with no code derivation.