# Quick Start

> Start from scratch with one shadcn command and a working table at /example, or add the blocks to a project you already have: one prerequisite, one install command, one paste

Source: https://data-table.openstatus.dev/docs/quick-start · Docs index: https://data-table.openstatus.dev/llms.txt · Full docs: https://data-table.openstatus.dev/llms-full.txt

Two ways in. Starting from nothing, one command creates the app and a working
table. Already have a shadcn project, one install command and one paste.

## Start from scratch

One shadcn command creates the Next.js app, initializes shadcn, and installs
a working example with every block it needs:

```bash
pnpm dlx shadcn@latest init @data-table-filters/data-table-example-infinite --name logs-viewer --template next -p lyra
cd logs-viewer
pnpm dev
```

Requires pnpm (`npm i -g pnpm`); `npx` and `npm run dev` work the same if you prefer npm.

Open [localhost:3000/example](http://localhost:3000/example): a table over
5,000 mock rows with a timeline chart, filters, facet counts, infinite scroll,
a command palette and a row sheet. It lives in `app/example` — the table
schema, a mock API route, and the page — so change the columns in
`app/example/table-schema.ts` and watch every surface follow, or delete the
folder once you have your own table.

That lands on Base UI, the shadcn default. For Radix, add `-b radix` before
`-p lyra`. The whole thing takes about a minute on a clean machine, most of
it `pnpm install`.

Using an agent instead? Paste this into Claude Code, Cursor or any agent
that can run commands. It reads the docs index first and ends on the same
page:

```text
Read https://data-table.openstatus.dev/llms.txt, then set up data-table-filters here: install @data-table-filters/data-table-example-infinite with the shadcn CLI (run `npx shadcn@latest init -d` first if the project has no components.json; if there is no app yet, create one with `pnpm dlx shadcn@latest init @data-table-filters/data-table-example-infinite --name logs-viewer --template next -p lyra` instead), start the dev server, and open /example.
```

That is the Quick Start. The rest of this page is for adding a table to a
project you already have.

## Add to an existing project

Three steps: a shadcn project, one install command, one paste.

### 1. Prerequisite

> **Prerequisite.** Works on either shadcn library: the CLI default, Base UI (`npx shadcn@latest init -d`), or Radix (`npx shadcn@latest init -b radix -p lyra`). CI installs into both and typechecks them on every registry change and nightly.

Any `"style"` in `components.json` works — `base-…` (Base UI), `radix-…`, or
the pre-v4 `new-york` / `default`. The blocks read the primitives from
whichever one you are on. No shadcn yet? `npx shadcn@latest init -d` in the
project first.

### 2. Install

One command installs the core `data-table` block (table engine, memory store
adapter, all 4 filter types) and `data-table-schema` (the schema system,
including `DataTableAuto`):

```bash
npx shadcn@latest add @data-table-filters/data-table @data-table-filters/data-table-schema
```

The CLI resolves the shadcn primitives the blocks need, rewrites `@/` import
paths to match your `components.json`, and injects the CSS variables.

### 3. Render

Paste this into a page — `app/page.tsx`, or `src/app/page.tsx` if the project
uses a `src` directory:

```tsx
import { DataTableAuto } from "@/components/data-table/data-table-auto";

const data = [
  {
    name: "Alice",
    role: "admin",
    rating: 5,
    created_at: "2026-01-15T10:00:00Z",
  },
  { name: "Bob", role: "user", rating: 3, created_at: "2026-02-20T14:30:00Z" },
];

export default function Page() {
  return <DataTableAuto data={data} />;
}
```

Columns, filters, display types, and cell renderers are auto-inferred from your
data, and the command palette and row detail sheet come along. See the
[/auto](/auto) example for a live demo.

![data-table with some filters and activated live mode](/assets/docs/data-table.png)

## You own the files

There is no `data-table-filters` package in your `package.json` — only the
blocks' own dependencies (TanStack Table, cmdk, and friends). The blocks landed
as source under `src/components/data-table/` and `src/lib/`. Edit them like any
other file in your repo. When the inferred table is not enough, [eject to the
Builder](/builder) or define a [Table Schema](/docs/table-schema) by hand.

## Agent Skill

Install the plugin in Claude Code:

```bash
/plugin marketplace add openstatushq/data-table-filters
/plugin install data-table-filters@openstatus
```

Or install the skill with any agent that supports the `skills` CLI:

```bash
npx skills add https://github.com/openstatushq/data-table-filters --skill data-table-filters
```

Let the agent handle the rest:

> Add a data table with filters to my project

It detects your stack, installs the right blocks, and wires them up. For agents without the skill, see
[For AI Agents](/docs/agents) — `llms.txt`, raw markdown docs, and Cursor rules.

## Blocks

Every block installs with the same command:

```bash
npx shadcn@latest add @data-table-filters/<block>
```

The registry is listed in the [shadcn directory](https://ui.shadcn.com/docs/directory),
so the name resolves with no `registries` entry in `components.json`. The JSON
form, `https://data-table.openstatus.dev/r/<block>.json`, works too.

| Block                          | Install                                            | What it adds                                                                           |
| ------------------------------ | -------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `data-table`                   | `@data-table-filters/data-table`                   | Core: table engine, store, 4 filter types, memory adapter                              |
| `data-table-schema`            | `@data-table-filters/data-table-schema`            | Declarative schema system with `col.*` factories and `DataTableAuto`                   |
| `data-table-cell`              | `@data-table-filters/data-table-cell`              | Cell renderers: badges, bars, heatmaps, status codes, timestamps                       |
| `data-table-sheet`             | `@data-table-filters/data-table-sheet`             | Row detail side panel                                                                  |
| `data-table-filter-command`    | `@data-table-filters/data-table-filter-command`    | Command palette with history and keyboard shortcuts                                    |
| `data-table-nuqs`              | `@data-table-filters/data-table-nuqs`              | nuqs URL state adapter                                                                 |
| `data-table-zustand`           | `@data-table-filters/data-table-zustand`           | zustand state adapter                                                                  |
| `data-table-drizzle`           | `@data-table-filters/data-table-drizzle`           | Drizzle ORM server-side helpers                                                        |
| `data-table-query`             | `@data-table-filters/data-table-query`             | React Query infinite query integration                                                 |
| `data-table-filter-command-ai` | `@data-table-filters/data-table-filter-command-ai` | Natural language → filter inference                                                    |
| `data-table-mcp`               | `@data-table-filters/data-table-mcp`               | MCP server endpoint for AI agents                                                      |
| `data-table-actions`           | `@data-table-filters/data-table-actions`           | Row and bulk actions rendered from server metadata                                     |
| `data-table-remote`            | `@data-table-filters/data-table-remote`            | Headless table that renders from an API endpoint's manifest                            |
| `data-table-chart`             | `@data-table-filters/data-table-chart`             | Timeline chart over the table: stacked buckets per level, drag to zoom the time filter |
| `data-table-example-infinite`  | `@data-table-filters/data-table-example-infinite`  | Ready-to-run `/example` route: schema, mock API, infinite table with URL state         |

> Looking to add natural language filtering? The `data-table-filter-command-ai` block translates queries like _"5xx errors last 24h"_ into structured filters using any LLM. See [AI Filters](/docs/ai-filters) for setup.

## Next Steps

- Upgrading an existing table? Follow [Upgrading from shadcn/ui Table](/docs/migrating-from-shadcn) to swap manual column definitions and useState for faceted filters and URL state
- Browse the [/infinite](/infinite) demo to see all components in action
- Learn about the [Table Schema](/docs/table-schema) builder for type-safe column definitions
- Explore the [UI Components](/docs/ui-components) available out of the box
- Rows live in Postgres? Follow [Drizzle ORM](/docs/drizzle-orm) for server-side filtering, facets, and cursor pagination
