data-table-filters

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

这是一个shadcn注册表，用于构建具备筛选、排序、无限滚动和虚拟化功能的数据表格。从核心块开始，再通过可选块进行扩展，包括命令面板、单元格渲染器、侧边面板、存储适配器、Schema生成、Drizzle ORM工具以及React Query集成。

Registry Blocks

注册表块

Install any block via

npx shadcn@latest add <url>

. The CLI handles dependencies, path rewriting, and CSS variable injection.

Block	Install URL	What it adds
data-table	`https://data-table.openstatus.dev/r/data-table.json`	Core: table engine, store, 4 filter types, memory adapter (~52 files)
data-table-filter-command	`.../r/data-table-filter-command.json`	Command palette with history + keyboard shortcuts
data-table-cell	`.../r/data-table-cell.json`	8 cell renderers (text, code, badge, boolean, number, status-code, level-indicator, timestamp)
data-table-sheet	`.../r/data-table-sheet.json`	Row detail side panel (auto-installs cells)
data-table-nuqs	`.../r/data-table-nuqs.json`	nuqs URL state adapter
data-table-zustand	`.../r/data-table-zustand.json`	zustand state adapter
data-table-schema	`.../r/data-table-schema.json`	Declarative schema system with `col.*` factories
data-table-drizzle	`.../r/data-table-drizzle.json`	Drizzle ORM server-side helpers (auto-installs schema)
data-table-query	`.../r/data-table-query.json`	React Query infinite query integration

All URLs use base

https://data-table.openstatus.dev

通过

npx shadcn@latest add <url>

命令安装任意块。CLI会处理依赖项、路径重写和CSS变量注入。

块名称	安装URL	新增内容
data-table	`https://data-table.openstatus.dev/r/data-table.json`	核心功能：表格引擎、存储、4种筛选类型、内存适配器（约52个文件）
data-table-filter-command	`.../r/data-table-filter-command.json`	带历史记录和键盘快捷键的命令面板
data-table-cell	`.../r/data-table-cell.json`	8种单元格渲染器（文本、代码、徽章、布尔值、数字、状态码、级别指示器、时间戳）
data-table-sheet	`.../r/data-table-sheet.json`	行详情侧边面板（自动安装单元格组件）
data-table-nuqs	`.../r/data-table-nuqs.json`	nuqs URL状态适配器
data-table-zustand	`.../r/data-table-zustand.json`	zustand状态适配器
data-table-schema	`.../r/data-table-schema.json`	带 `col.*` 工厂函数的声明式Schema系统
data-table-drizzle	`.../r/data-table-drizzle.json`	Drizzle ORM服务端工具（自动安装Schema）
data-table-query	`.../r/data-table-query.json`	React Query无限查询集成

所有URL的基础地址为

https://data-table.openstatus.dev

。

Quick Start

快速开始

Run
```
scripts/detect-stack.sh
```
to detect the user's project setup

Install core:

npx shadcn@latest add https://data-table.openstatus.dev/r/data-table.json

Scaffold a minimal working table (see below)
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.

运行
```
scripts/detect-stack.sh
```
检测用户的项目配置

安装核心块：

npx shadcn@latest add https://data-table.openstatus.dev/r/data-table.json

搭建一个最简可用表格（见下文）
根据需要添加额外块

使用Next.js？ 参考data-table-filters仓库——这是一个集成了所有块的完整Next.js应用。

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

注意：
DataTableInfinite
内部会渲染
DataTableProvider
，该组件已用
ControlsProvider
和
DataTableStoreSync
包裹子组件。你无需单独添加这些组件。唯一需要的包裹组件是
DataTableStoreProvider
（用于BYOS适配器）。

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>[] = [
  /* 用户自定义列 */
];
const filterFields: DataTableFilterField<YourData>[] = [
  /* 用户自定义筛选字段 */
];

export function MyTable({ data }: { data: YourData[] }) {
  const adapter = useMemoryAdapter(/* schema定义 */);
  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.

通过

npx shadcn@latest add

命令安装块后，将其集成到表格中。

Command Palette →

commandSlot

命令面板 →

commandSlot

tsx

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

tsx

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

Sheet Detail Panel →

sheetSlot

侧边详情面板 →

sheetSlot

tsx

<DataTableInfinite
  sheetSlot={
    <DataTableSheetDetails title="Details">{content}</DataTableSheetDetails>
  }
/>

tsx

<DataTableInfinite
  sheetSlot={
    <DataTableSheetDetails title="详情">{content}</DataTableSheetDetails>
  }
/>

Cell Renderers → column definitions

单元格渲染器 → 列定义

tsx

import { DataTableCellBadge } from "@/components/data-table/data-table-cell";
// Use in columnDef.cell

tsx

import { DataTableCellBadge } from "@/components/data-table/data-table-cell";
// 在columnDef.cell中使用

Custom Filter Types →

FILTER_COMPONENTS

自定义筛选类型 →

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;

核心块已包含4种筛选类型。要添加自定义类型：

tsx

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

All Slot Props

所有插槽属性

DataTableInfinite

accepts:

commandSlot

sheetSlot

toolbarActions

chartSlot

footerSlot

See references/component-catalog.md for full wiring details.

DataTableInfinite

支持：

commandSlot

、

sheetSlot

、

toolbarActions

、

chartSlot

、

footerSlot

。

完整集成细节请参考references/component-catalog.md。

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.

memory（默认）——临时存储，零配置。适用于原型开发、嵌入式组件、构建工具。
nuqs——URL状态。支持可分享链接、可收藏的筛选条件。需要框架配置。
zustand——客户端状态。适用于已使用zustand的应用、复杂应用状态管理。

安装适配器块，替换对应的Provider。详情请参考references/store-adapters.md。

Schema Generation

Schema生成

Install:

npx shadcn@latest add .../r/data-table-schema.json

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

Presets:

col.presets.logLevel()

.httpStatus()

.duration()

.timestamp()

.traceId()

.pathname()

.httpMethod()

See references/schema-api.md.

安装命令：

npx shadcn@latest add .../r/data-table-schema.json

将数据模型映射为

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

预设项：

col.presets.logLevel()

、

.httpStatus()

、

.duration()

、

.timestamp()

、

.traceId()

、

.pathname()

、

.httpMethod()

。

详情请参考references/schema-api.md。

Server-Side Integration

服务端集成

Install:

npx shadcn@latest add .../r/data-table-drizzle.json

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.

安装命令：

npx shadcn@latest add .../r/data-table-drizzle.json

使用

createDrizzleHandler({ db, table, columnMapping, cursorColumn, schema })

搭建路由处理器。

对于非Drizzle ORM：实现响应格式

{ data, facets, totalRowCount, filterRowCount, nextCursor, prevCursor }

。

详情请参考references/drizzle-integration.md。

Fetch Layer

获取层

Install:

npx shadcn@latest add .../r/data-table-query.json

Wire

createDataTableQueryOptions({ queryKeyPrefix, apiEndpoint, searchParamsSerializer })

See references/fetch-layer.md.

安装命令：

npx shadcn@latest add .../r/data-table-query.json

集成

createDataTableQueryOptions({ queryKeyPrefix, apiEndpoint, searchParamsSerializer })

。

详情请参考references/fetch-layer.md。

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.

缺少CSS变量：核心块会注入
```
--color-success/warning/error/info
```
。检查CSS中是否已应用这些cssVars。
导入路径不匹配：shadcn CLI会根据
```
components.json
```
中的别名重写
```
@/
```
路径。
nuqs：无提示失败或崩溃：需要两个必要的配置步骤——在根布局中添加
```
<NuqsAdapter>
```
，并在表格组件周围包裹
```
<Suspense>
```
。详情请参考references/store-adapters.md。
nuqs：加载时未从URL应用筛选条件：将服务端解析的搜索参数作为
```
initialState
```
传递给nuqs适配器。详情请参考references/store-adapters.md中的SSR水合部分。
nuqs：空字符串导致的幽灵筛选器：使用
```
field.string()
```
（默认值为null），而非
```
field.string().default("")
```
。
侧边面板下拉菜单缺失：
```
SheetField.type
```
必须与筛选类型匹配（不能是
```
"readonly"
```
）才能显示筛选下拉菜单。使用
```
generateSheetFields()
```
从筛选配置自动派生。
筛选器未渲染：验证筛选类型字符串是否与
```
FILTER_COMPONENTS
```
的键匹配。
Tailwind v4：注册表针对v4版本构建，类语法与v3不同。".replace(/"/g, '"'),

data-table-filters

Original

Translation

Data Table Filters

数据表格筛选器

Registry Blocks

注册表块

Quick Start

快速开始

Minimal Working Table (Memory Adapter)

最简可用表格（内存适配器）

Wiring Extension Blocks

扩展块集成

Command Palette →
`commandSlot`

命令面板 →
`commandSlot`

Sheet Detail Panel →
`sheetSlot`

侧边详情面板 →
`sheetSlot`

Cell Renderers → column definitions

单元格渲染器 → 列定义

Custom Filter Types →
`FILTER_COMPONENTS`

自定义筛选类型 →
`FILTER_COMPONENTS`

All Slot Props

所有插槽属性

Store Adapter Configuration

存储适配器配置

Schema Generation

Schema生成

Server-Side Integration

服务端集成

Fetch Layer

获取层

Troubleshooting

故障排查