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.

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 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).

"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

<DataTableInfinite
  commandSlot={<DataTableFilterCommand schema={schema} tableId="my-table" />}
/>

Sheet Detail Panel → sheetSlot

<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).

// 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.

// 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 })

// 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

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:

import { FILTER_COMPONENTS } from "@/components/data-table/data-table-filter-controls";
FILTER_COMPONENTS.myCustom = MyCustomFilterComponent;

AI Command Palette → commandSlot

<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.

All Slot Props

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

See 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.

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.

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:

import { DataTableAuto } from "@/components/data-table/data-table-auto";
import data from "./data.json";

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

Includes command palette and sheet detail panel out of the box. See the /auto route in this repo for a working example.

Lower-Level API

import { inferSchemaFromJSON } from "@/lib/table-schema/infer";
import { createTableSchema } from "@/lib/table-schema";

const schemaJson = inferSchemaFromJSON(data);
const { definition } = createTableSchema.fromJSON(schemaJson);

See references/auto-infer.md for inference heuristics, smart enhancements, and customization.

Server-Side Integration

Install: npx shadcn@latest add @data-table-filters/data-table-drizzle

Scaffold route handler with createDrizzleHandler({ db, table, columnMapping, cursorColumn, schema }).

For non-Drizzle ORMs: implement response shape { data, facets, totalRowCount, filterRowCount, nextCursor, prevCursor }.

See references/drizzle-integration.md.

Fetch Layer

Install: npx shadcn@latest add @data-table-filters/data-table-query

Wire createDataTableQueryOptions({ queryKeyPrefix, apiEndpoint, searchParamsSerializer }).

Defaults to a same-origin fetch and a SuperJSON body. For anyone else's API, pass transport (baseUrl, headers as a sync/async function, credentials, parseResponse) and a pagination strategy — timestampCursorPagination() (default, bidirectional), opaqueCursorPagination(), or offsetPagination({ size }). schemaJsonParser(schema) revives timestamp columns from plain ISO strings, so the endpoint need not adopt SuperJSON. A non-2xx or unparseable body throws DataTableFetchError with status, url and a body snippet.

See references/fetch-layer.md.

Headless Table (Point at an Endpoint)

Install: npx shadcn@latest add @data-table-filters/data-table-remote

For a table whose data and endpoint are owned elsewhere, with no per-column code in the app.

Server — publish a manifest describing the table:

// app/<table>/api/schema/route.ts
const handler = createTableManifestHandler(
  createTableManifest({
    schema: tableSchema,
    primaryKey: "uuid", // the column that identifies a row on the wire
    rowLabel: "{method} {pathname}", // template over column keys, for a11y
    capabilities: { facets: true, totalRowCount: true, chart: true },
    defaults: { sort: { id: "date", desc: true }, size: 40 },
  }),
);
export const GET = (request: Request) => handler(request);

Pass a function instead of a value when the manifest depends on the request (per-tenant columns, permission-dependent actions). Served with an ETag, so a revalidation is a 304.

Client:

<DataTableRemote
  manifestEndpoint="/logs/api/schema" // data endpoint defaults to this minus /schema
  searchParamsSerializer={searchParamsSerializer}
  initialManifest={snapshot} // optional — skips the round trip before first paint
  transport={{ headers: async () => ({ authorization: await token() }) }}
  renderers={{ pathname: { cell: (v) => <PathnameCell value={String(v)} /> } }}
/>

Key points:

• Capabilities default to off. Declare only what the endpoint implements; the table degrades (client-side faceting, blank counts, no live button, no chart) rather than rendering empty.
• Renderers do not serialize. Named displays (badge, bar, status-code, …) travel as data; use applyRenderers / the renderers prop for the rest. The descriptor is untouched, so the schema still round-trips.
• The manifest is untrusted. Bounded columns and actions; action hrefs restricted to the page's origin unless allow-listed via allowedActionOrigins.
• Snapshot to avoid the round trip. pullManifestModule(url) writes a typed module; pass it as initialManifest. It still revalidates at runtime.
• Verify an endpoint with runEndpointConformance({ url, manifest }) and formatConformanceReport.

Troubleshooting

• Missing CSS vars: Core injects --color-success/warning/error/info. Check cssVars applied to CSS.
• Import path mismatches: shadcn CLI rewrites @/ paths per components.json aliases.
• nuqs: silent failure or crash: Two required setup steps — <NuqsAdapter> in root layout AND <Suspense> around the table component. See references/store-adapters.md.
• nuqs: filters not applied from URL on load: Pass server-parsed search params as initialState to the nuqs adapter. See the SSR Hydration section in references/store-adapters.md.
• nuqs: phantom filters with empty string: Use field.string() (null default), not field.string().default("").
• Sheet dropdown missing: SheetField.type must match the filter type (not "readonly") to get the filter dropdown. Use generateSheetFields() to auto-derive from filter config.
• Filter not rendering: Verify filter type string matches FILTER_COMPONENTS key.
• Tailwind v4: Registry targets v4. Class syntax differs from v3.