data-table-filters

# Data Table Filters A shadcn registry for building filterable, sortable data tables with infinite scroll and virtualization. Start with the core block, then extend with optional blocks for command palette, cell renderers, sheet panels, store adapters, schema generation, Drizzle ORM helpers, and React Query integration. > **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. ## Registry Blocks Install any block via `npx shadcn@latest add @data-table-filters/<block>`. The CLI handles dependencies, path rewriting, and CSS variable injection. | Block | Install | What it adds | | -------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **data-table** | `@data-table-filters/data-table` | Core: table engine, store, 4 filter types, memory adapter (63 files) | | **data-table-filter-command** | `@data-table-filters/data-table-filter-command` | Command palette with history + keyboard shortcuts | | **data-table-cell** | `@data-table-filters/data-table-cell` | 12 cell renderers (text, code, number, bar, heatmap, gauge, badge, boolean, star, status-code, level-indicator, timestamp) | | **data-table-sheet** | `@data-table-filters/data-table-sheet` | Row detail side panel (auto-installs cells) | | **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-schema** | `@data-table-filters/data-table-schema` | Declarative schema system with `col.*` factories | | **data-table-drizzle** | `@data-table-filters/data-table-drizzle` | Drizzle ORM server-side helpers (auto-installs schema) | | **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` | AI-powered natural language → filter inference (provider-agnostic) | | **data-table-mcp** | `@data-table-filters/data-table-mcp` | MCP server endpoint for AI agents (stateless, serverless-compatible) | | **data-table-actions** | `@data-table-filters/data-table-actions` | Row and bulk actions rendered from server metadata (requires drizzle) | | **data-table-remote** | `@data-table-filters/data-table-remote` | Headless table driven by an endpoint's manifest — schema, capabilities, row identity | | **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 | Blocks install by name from the shadcn registry directory; the JSON form `https://data-table.openstatus.dev/r/<block>.json` works too. ## Quick Start 1. Run `scripts/detect-stack.sh` to detect the user's project setup. It reports which component library the project is on — either works. If it prints `shadcn/ui: not initialized`, initialize with `npx shadcn@latest init -d` (or `init -b radix -p lyra` for Radix) first, then continue. No project at all yet? `pnpm dlx shadcn@latest init @data-table-filters/data-table-example-infinite --name logs-viewer --template next -p lyra` creates a Next.js app with shadcn initialized and a working `/example` route (timeline chart, filters, infinite scroll, row sheet) installed, with every block it needs (add `-b radix` before `-p lyra` for Radix). Requires pnpm (`npm i -g pnpm`); `npx` and `npm run dev` work the same if you prefer npm. Then `cd logs-viewer`, run the dev server, open http://localhost:3000/example, and edit `app/example/table-schema.ts` — or continue with step 2 for a table of your own. 2. Install core + schema: `npx shadcn@latest add @data-table-filters/data-table @data-table-filters/data-table-schema` 3. Scaffold a minimal working table (see below), or render `<DataTableAuto data={rows} />` when the data shape is unknown 4. Extend with additional blocks as needed > **Next.js?** Use the [data-table-filters repo](https://github.com/openstatushq/data-table-filters) as a reference — it's a full Next.js app with all blocks wired up. ### Minimal Working Table (Memory Adapter) > **Note:** `DataTableInfinite` internally renders `DataTableProvider`, which already wraps children with `ControlsProvider` and `DataTableStoreSync`. You do NOT need to add these separately. The only wrapper you need is `DataTableStoreProvider` (for the BYOS adapter). ```tsx "use client"; import { DataTableInfinite } from "@/components/data-table/data-table-infinite"; import type { DataTableFilterField } from "@/components/data-table/types"; import { useMemoryAdapter } from "@/lib/store/adapters/memory"; import { DataTableStoreProvider } from "@/lib/store/provider/DataTableStoreProvider"; import type { ColumnDef } from "@tanstack/react-table"; const columns: ColumnDef<YourData>[] = [ /* user's columns */ ]; const filterFields: DataTableFilterField<YourData>[] = [ /* user's filters */ ]; export function MyTable({ data }: { data: YourData[] }) { const adapter = useMemoryAdapter(/* schema definition */); return ( <DataTableStoreProvider adapter={adapter}> <DataTableInfinite columns={columns} data={data} filterFields={filterFields} /> </DataTableStoreProvider> ); } ``` ## Wiring Extension Blocks After installing a block via `npx shadcn@latest add`, wire it into the table. ### Command Palette → `commandSlot` ```tsx <DataTableInfinite commandSlot={<DataTableFilterCommand schema={schema} tableId="my-table" />} /> ``` ### Sheet Detail Panel → `sheetSlot` ```tsx <DataTableInfinite sheetSlot={ <DataTableSheetDetails title="Details">{content}</DataTableSheetDetails> } /> ``` ### Floating Bar (Bulk Actions) → `floatingBarSlot` Add `col.select()` to the schema to enable multi-row selection with checkboxes. Wrap actions in `DataTableFloatingBar` — it reads selection state from context (same pattern as `DataTableSheetDetails` for `sheetSlot`). ```tsx // In table-schema.tsx export const tableSchema = createTableSchema({ select: col.select().size(37), // ... other columns }); // In client.tsx import { DataTableFloatingBar } from "@/components/data-table/data-table-floating-bar"; <DataTableInfinite floatingBarSlot={ <DataTableFloatingBar> {({ rows }) => ( <Button variant="outline" size="sm" onClick={() => console.log(rows)}> Export ({rows.length}) </Button> )} </DataTableFloatingBar> } />; ``` ### Row Actions → `data-table-actions` Install: `npx shadcn@latest add @data-table-filters/data-table-actions` (requires the drizzle block). Actions are declared once on the server, next to their Drizzle handler. The list endpoint advertises them (`meta.actions`) and stamps each row with the ids that apply (`_actions`); the UI renders from that JSON and never learns what an action does. ```ts // app/<table>/api/actions.ts export const actionHandler = createActionHandler({ db, table, filters, columnMapping, // same as createDrizzleHandler, plus the id column idColumn: "uuid", basePath: "/<table>/api/actions", actions: { acknowledge: { label: "Acknowledge", scope: ["row", "bulk", "filter"], when: { level: ["error"] }, // filter values — evaluated in JS for _actions, compiled to SQL as the WHERE guard handler: async (ctx, tx) => ( await tx .update(table) .set({ level: "warning" }) .where(ctx.where) .returning() ).length, }, }, }); // GET route: data = actionHandler.annotate(result.data); meta.actions = actionHandler.descriptors // POST app/<table>/api/actions/[id]/route.ts: actionHandler.execute(id, await req.json(), { actor }) ``` ```tsx // client.tsx <DataTableActionsProvider actions={meta?.actions} getRowId={(r) => r.uuid} queryKeyPrefix="<prefix>" > <DataTableInfinite columns={[...generateColumns(schema), createActionsColumn()]} floatingBarSlot={ <DataTableFloatingBar> {({ rows }) => <DataTableActionsBar rows={rows} />} </DataTableFloatingBar> } /> </DataTableActionsProvider> ``` `_actions` is a hint; the handler's `ctx.where` (ids ∩ `when`) is the authority, so `applied` may be lower than the ids sent. Actions enqueue (flip a status), they don't execute. Outcomes are sonner toasts — mount `<Toaster />` once in the layout (`npx shadcn@latest add sonner`). ### Cell Renderers → column definitions ```tsx import { DataTableCellBadge } from "@/components/data-table/data-table-cell"; // Use in columnDef.cell ``` ### Custom Filter Types → `FILTER_COMPONENTS` All 4 filter types ship with core. To add custom types: ```tsx import { FILTER_COMPONENTS } from "@/components/data-table/data-table-filter-controls"; FILTER_COMPONENTS.myCustom = MyCustomFilterComponent; ``` ### AI Command Palette → `commandSlot` ```tsx <DataTableInfinite commandSlot={ <DataTableFilterAICommand schema={filterSchema.definition} tableSchema={tableSchema.definition} api="/api/ai-filters" tableId="my-table" /> } /> ``` Requires an API route that streams AI results. See [references/ai-filters.md](references/ai-filters.md). ### All Slot Props `DataTableInfinite` accepts: `commandSlot`, `sheetSlot`, `toolbarActions`, `chartSlot`, `footerSlot`, `floatingBarSlot`. See [references/component-catalog.md](references/component-catalog.md) for full wiring details. ## Store Adapter Configuration - **memory** (default) — Ephemeral, zero config. For prototyping, embedded components, builders. - **nuqs** — URL state. Shareable links, bookmarkable filters. Requires framework setup. - **zustand** — Client state. For existing zustand apps, complex app state. Install adapter block, swap in provider. See [references/store-adapters.md](references/store-adapters.md). ## Schema Generation Install: `npx shadcn@latest add @data-table-filters/data-table-schema` Map data model → `createTableSchema` + `col.*`: - `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")` - `select` → `col.select()` (checkbox row selection, not filterable) Presets: `col.presets.logLevel()`, `.httpStatus()`, `.duration()`, `.timestamp()`, `.traceId()`, `.pathname()`, `.httpMethod()`. See [references/schema-api.md](references/schema-api.md). ## Auto-Infer (Zero-Config from JSON) For raw JSON data with no predefined schema, use `DataTableAuto` or the lower-level `inferSchemaFromJSON` + `createTableSchema.fromJSON` pipeline. This auto-generates columns, filters, sheet fields, and column visibility from the data itself. ### DataTableAuto Component Drop-in component — pass JSON data, get a fully functional table: ```tsx