Installation

PrerequisitesCopy Anchor Link

• React 18 or 19
• A shadcn/ui setup with Tailwind CSS v4
• For Next.js, the App Router (14.1+). For react-router, version 6.4+ or 7. Any other React app works too.

Choose how to installCopy Anchor Link

tablecn has two blocks. Take one or both:

• @tablecn/data-table: the table, with search, sorting, pages, a column layout users can change, row selection and inline editing.
• @tablecn/filter-builder: the filter builder, "Where Status is Paid and Amount is over 50". It works with the table, or on its own.

The @tablecn registryCopy Anchor Link

tablecn is listed in the shadcn registry directory, so the CLI knows @tablecn already: skip to Add the blocks.

The CLI reads the style in your components.json and gives you the matching version: Radix UI for radix-* (and older styles like new-york), Base UI for base-*, React Aria for aria-*. All three have the same files and props.

Add the registry yourselfCopy Anchor Link

With an older shadcn CLI, or to write the URL down in your project, add it to components.json:

pnpm dlx shadcn@latest registry add @tablecn=https://table-cn.vercel.app/r/{style}/{name}.json

Or by hand:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "registries": {
    "@tablecn": "https://table-cn.vercel.app/r/{style}/{name}.json"
  }
}

Add the blocksCopy Anchor Link

pnpm dlx shadcn@latest add @tablecn/data-table @tablecn/filter-builder

The CLI also installs the packages the blocks use (@querycn/*, TanStack Table…) and adds any shadcn component you don't have yet.

Next.js apps add the Next.js adapter too. The registry leaves it out, since only Next.js needs it:

pnpm add @querycn/filter-next

Then build your first page: Quick start.

Notes on --pathCopy Anchor Link

To put a block somewhere else than components/, pass --path, one block per command:

pnpm dlx shadcn@latest add @tablecn/data-table --path src/shared/data-table
pnpm dlx shadcn@latest add @tablecn/filter-builder --path src/shared/filter

Every file of the block goes to that folder, with the imports between them rewritten to match. Import from there: @/shared/data-table/data-table.

To skip that cleanup, point the components alias in components.json at the parent folder instead ("components": "@/shared"), add the blocks without --path, then set it back. The shadcn components then stay in components/ui/.

--dry-run lists the default folders even with --path; the real run uses it.

Headless: npm onlyCopy Anchor Link

To build your own UI, install the packages and skip the blocks:

pnpm add @querycn/table-react @querycn/filter-react @tanstack/react-table

Next.js apps add @querycn/filter-next in both cases.

PackagesCopy Anchor Link

Peer dependencies are shared with your app: it installs them once, and every package uses that one copy. The shadcn registry installs them with the blocks; with npm, install them yourself, as in the commands above.

UpdatingCopy Anchor Link

New versions are listed in the Changelog. Update the packages as usual:

pnpm add @querycn/table-react@latest @querycn/filter-react@latest

The blocks are your files, so they don't update on their own. To take a new version of one, add it again with --overwrite:

pnpm dlx shadcn@latest add @tablecn/data-table --overwrite

It replaces your copy, your changes included: commit first, then review the diff and bring your changes back.

TroubleshootingCopy Anchor Link

ERR_PNPM_NO_MATURE_MATCHING_VERSIONCopy Anchor Link

Recent pnpm versions only install a version once it's been published for a day (minimumReleaseAge, 1440 minutes by default), to keep you away from a compromised release. Right after a tablecn release, the blocks ask for @querycn versions younger than that, so shadcn add fails with pnpm. Wait a day, or let the @querycn packages through:

minimumReleaseAgeExclude:
  - "@querycn/*"

npm, yarn and bun don't have this check by default.

Next stepsCopy Anchor Link