data-table-filters / rules

---
description: Install and wire up data-table-filters — filterable React data tables with server-side filtering, faceted counts, infinite scroll, and virtualization, delivered as shadcn registry blocks.
globs:
alwaysApply: false
---

# data-table-filters

Copy this file into any project that uses data-table-filters
(`.cursor/rules/data-table-filters.mdc`) to give Cursor the same instructions the
Claude Code skill provides.

Blocks are installed into the repo with the shadcn CLI — this is not an npm
dependency. Stack: React 19+, TanStack Table v8, Tailwind CSS v4, shadcn/ui.

> **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.
No library check needed before installing: the blocks resolve their primitives
from whichever library `components.json` names.

No project yet? One command creates a Next.js app, initializes shadcn, and
installs a working `/example` route with every block it needs (add `-b radix`
before `-p lyra` for Radix); `cd logs-viewer`, run the dev server and open
http://localhost:3000/example:

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

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

Full docs for agents:

- MCP server (ask instead of fetch): https://data-table.openstatus.dev/api/mcp
- Index: https://data-table.openstatus.dev/llms.txt
- Everything in one file: https://data-table.openstatus.dev/llms-full.txt
- Block catalog: https://data-table.openstatus.dev/r/index.md
- Any docs page as markdown: append `.md`, e.g. `/docs/drizzle-orm.md`

## Blocks

Blocks install by name from the shadcn registry directory; the JSON form `https://data-table.openstatus.dev/r/<block>.json` works too.

| Block                          | Install when                                                                                   |
| ------------------------------ | ---------------------------------------------------------------------------------------------- |
| `data-table`                   | Always — table engine, 4 filter types, infinite scroll, virtualization, memory store            |
| `data-table-schema`            | One definition should drive columns, filters, sheet, and sorting (required by drizzle/mcp/ai)   |
| `data-table-cell`              | Columns need badges, bars, heatmaps, status codes, timestamps                                   |
| `data-table-sheet`             | Clicking a row opens a detail panel                                                             |
| `data-table-filter-command`    | cmd+k filter palette with history                                                               |
| `data-table-nuqs`              | Filter state lives in the URL (default for Next.js)                                             |
| `data-table-zustand`           | Filter state lives in client app state                                                          |
| `data-table-drizzle`           | Rows live in SQL and must be filtered server-side — **the block for large tables**              |
| `data-table-query`             | The table fetches pages from an API endpoint                                                    |
| `data-table-filter-command-ai` | Natural-language filtering                                                                      |
| `data-table-mcp`               | Agents should query the table over MCP                                                          |
| `data-table-actions`           | Users need to act on rows — replay, acknowledge, delete (requires drizzle)                       |
| `data-table-remote`            | The table should render from an API endpoint's manifest, with no per-column code                |
| `data-table-chart`            | A stacked timeline above the table; the endpoint returns `meta.chartData` (Drizzle handler does, or use `bucketChartData`) |
| `data-table-example-infinite`            | A complete table on screen before any data is wired up — ships app/example and every block it needs |

## Large table (server-side, 100k+ rows)

```bash
npx shadcn@latest add \
  @data-table-filters/data-table \
  @data-table-filters/data-table-schema \
  @data-table-filters/data-table-cell \
  @data-table-filters/data-table-sheet \
  @data-table-filters/data-table-drizzle \
  @data-table-filters/data-table-query \
  @data-table-filters/data-table-nuqs
```

1. `createTableSchema` with `col.*` factories — one definition per table.
2. Route handler: `createDrizzleHandler({ db, table, columnMapping, cursorColumn, schema })`.
3. Client: `createDataTableQueryOptions({ queryKeyPrefix, apiEndpoint, searchParamsSerializer })`.
4. Render `<DataTableInfinite>` inside `<DataTableStoreProvider adapter={adapter}>`.

Filtering, faceted counts, sorting, and cursor pagination all execute in SQL.

## Client-side table

```bash
npx shadcn@latest add \
  @data-table-filters/data-table \
  @data-table-filters/data-table-cell \
  @data-table-filters/data-table-sheet
```

Use `useMemoryAdapter`. No API route, no schema block.

## Table pointed at an API endpoint

```bash
npx shadcn@latest add \
  @data-table-filters/data-table \
  @data-table-filters/data-table-schema \
  @data-table-filters/data-table-query \
  @data-table-filters/data-table-nuqs \
  @data-table-filters/data-table-remote
```

Serve a manifest with `createTableManifest` + `createTableManifestHandler`, then
render `<DataTableRemote manifestEndpoint="/api/logs/schema" />`. Declare only
the capabilities the endpoint implements — everything defaults to off and the
table degrades rather than rendering empty. Pass `initialManifest` (a build-time
snapshot or a server prefetch) to skip the round trip before first paint, and
`transport` for another origin, auth headers, or a plain-JSON API.

## Schema mapping

- `string` → `col.string().filterable("input")`
- `number` → `col.number().filterable("slider", { min, max })`
- `boolean` → `col.boolean().filterable("checkbox")`
- `Date` → `col.timestamp().filterable("timerange")`
- `enum` → `col.enum(values).filterable("checkbox")`
- row selection → `col.select()`

Presets: `col.presets.logLevel()`, `.httpStatus()`, `.duration()`, `.timestamp()`,
`.traceId()`, `.pathname()`, `.httpMethod()`.

## Slots

`DataTableInfinite` accepts `commandSlot`, `sheetSlot`, `toolbarActions`,
`chartSlot`, `footerSlot`, `floatingBarSlot`.

## Gotchas

- `DataTableInfinite` already renders `DataTableProvider`, `ControlsProvider`, and
  `DataTableStoreSync`. Only add `DataTableStoreProvider`.
- nuqs needs **both** `<NuqsAdapter>` in the root layout and `<Suspense>` around
  the table, plus server-parsed search params as `initialState` for SSR.
- `field.string()`, never `field.string().default("")` — the latter creates
  phantom filters.
- Tailwind v4 only; v3 class syntax breaks silently.
- `SheetField.type` must match the filter type to render a dropdown, or use
  `generateSheetFields()`.
- Filter not rendering? The filter type string must be a key of
  `FILTER_COMPONENTS`.

More agent context in openstatusHQ/data-table-filters

19 other files this repository gives its agents.