Installation

The shadcn CLI distributes gridcn entirely from the hosted @gridcn registry (gridcn.vercel.app), built from this repository's GitHub registry. There is no npm package: the source files are copied into your project.

Install the core grid

pnpm dlx shadcn@latest add @gridcn/data-grid

The CLI resolves the @gridcn registry from the hosted site (gridcn.vercel.app) — no namespace registration needed. To pin a tag, branch, or commit, use the GitHub registry path instead: npx shadcn add DammersCode/gridcn/data-grid#v1.0.0.

The command installs the engine: range selection, keyboard, editing, built-in cell types, and spreadsheet clipboard. The Manual tab links every file and folder to its source in the repository, for an install without the CLI.

Add optional pieces

Each add-on is independently installable and depends only on the core:

npx shadcn add @gridcn/data-grid-fill
npx shadcn add @gridcn/data-grid-presence
npx shadcn add @gridcn/data-grid-pinned-rows
npx shadcn add @gridcn/data-grid-history
npx shadcn add @gridcn/data-grid-toolbar
npx shadcn add @gridcn/data-grid-sort-list
npx shadcn add @gridcn/data-grid-context-menu
npx shadcn add @gridcn/data-grid-keybindings
npx shadcn add @gridcn/data-grid-io
npx shadcn add @gridcn/data-grid-url-state
npx shadcn add @gridcn/data-grid-lazy
npx shadcn add @gridcn/data-grid-pagination

See each feature's docs page for what it adds and its own install command.

Pinned installs

The hosted @gridcn registry always serves the current deploy of main. To pin a specific tag, branch, or commit, use the GitHub registry path and append #<ref> after the item name:

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

Without a ref, the CLI uses the repository's default branch.

Alternative: GitHub registry (no setup)

The same items are available directly from this repository's GitHub registry — no namespace registration, and the only path that supports ref pinning:

npx shadcn add DammersCode/gridcn/data-grid

Both paths install the same files from the same source.

Prerequisites

Your project needs shadcn/ui already initialized (npx shadcn init), Tailwind v4, and React 19. See shadcn's own installation guide if you have not run npx shadcn init yet. This command creates components.json at the root of your project. gridcn's CLI commands read that file to find your aliases and styling. See Project status & compatibility for why React 19 is a hard floor, plus the Node and TypeScript floors.

The core item of gridcn has exactly one npm dependency: zustand. The table below lists the dependency of each add-on.

Add-on	Runtime dependency	Dev dependency
Core (`data-grid`)	`zustand`	none
`data-grid-toolbar`	`@dnd-kit/react`	none
`data-grid-sort-list`	`@dnd-kit/react`	none
`data-grid-io`	`xlsx`, `papaparse` (lazy-loaded)	`@types/papaparse`
`data-grid-url-state`	`nuqs`	none
All other add-ons	none beyond the core	none

Where files land

registry:component and registry:block files install under the aliases.components path in your components.json (@/components by default). So the data-grid item lands at components/data-grid/*, with one file per exported symbol, and a single public barrel at components/data-grid/data-grid.tsx. Import from that barrel, not from individual files.

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

Add-ons follow the same pattern (components/data-grid-history/data-grid-history.ts, etc.).

Framework notes

Next.js

gridcn works by default in the App Router. Every grid component is a client component, with "use client" at the top of each file, so no extra configuration is necessary.

Vite

gridcn works the same way in Vite. The CLI detects your Vite and shadcn setup from components.json. If you use React 19 with Vite, make sure that your vite.config.ts alias resolution matches the aliases in components.json. The CLI reads the same file to decide where to write files.

Non-default aliases

Your components.json can use non-default aliases. An example is components pointed at src/components instead of @/components, or no @/* path prefix at all. If so, the shadcn CLI rewrites the internal @/registry/...-style imports of gridcn to your aliases automatically on install.

Known problem: missing alias

If an install leaves an import unresolved, make sure that:

aliases.components, aliases.ui, aliases.lib, and aliases.hooks are all set in components.json. When an alias is missing, some CLI versions leave the import unresolved, and other CLI versions rewrite it to a wrong path. The exact result depends on the CLI version.
Your tsconfig.json or vite.config.ts path mapping matches those aliases. The CLI writes files assuming that the mapping exists. It does not create the mapping for you.

If imports are still wrong after install, fix the handful of import lines by hand instead of fighting the alias resolver. The files belong to you now.

// Before (unresolved after install, missing aliases.hooks)
import { useDataGridActions } from "hooks/use-data-grid-actions";

// After (matches your tsconfig.json / vite.config.ts path mapping)
import { useDataGridActions } from "@/hooks/use-data-grid-actions";

Verify

Add the columns and data shape of the hero demo from the quick start to any page. Click a cell, type a value, and press Enter to make sure that editing works. If the grid displays without styles, make sure that your global.css imports Tailwind and that shadcn's base tokens are present. gridcn uses only existing shadcn tokens, with no new CSS variables beyond --grid-row-height and --grid-pin-shadow (the pinned-column boundary shadow color). Theme --grid-pin-shadow in your global.css, like the docs site does: the grid uses the variable without a fallback, so an undefined value renders an invisible shadow. See Styling & theming.

On this page