Back to Details

shadcn

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

@json-render/shadcn

@json-render/shadcn

Pre-built shadcn/ui component definitions and implementations for json-render. Provides 36 components built on Radix UI + Tailwind CSS.
为json-render预构建的shadcn/ui组件定义与实现，提供了36个基于Radix UI + Tailwind CSS构建的组件。

Two Entry Points

两个入口

Entry PointExportsUse For
@json-render/shadcn/catalog
shadcnComponentDefinitions
Catalog schemas (no React dependency, safe for server)
@json-render/shadcn
shadcnComponents
React implementations
入口导出内容适用场景
@json-render/shadcn/catalog
shadcnComponentDefinitions
目录schema（无React依赖，服务端可安全使用）
@json-render/shadcn
shadcnComponents
React组件实现

Usage Pattern

使用模式

Pick the components you need from the standard definitions. Do not spread all definitions -- explicitly select what your app uses:
typescript
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
import { defineRegistry } from "@json-render/react";
import { shadcnComponents } from "@json-render/shadcn";

// Catalog: pick definitions
const catalog = defineCatalog(schema, {
  components: {
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,
    Heading: shadcnComponentDefinitions.Heading,
    Button: shadcnComponentDefinitions.Button,
    Input: shadcnComponentDefinitions.Input,
  },
  actions: {},
});

// Registry: pick matching implementations
const { registry } = defineRegistry(catalog, {
  components: {
    Card: shadcnComponents.Card,
    Stack: shadcnComponents.Stack,
    Heading: shadcnComponents.Heading,
    Button: shadcnComponents.Button,
    Input: shadcnComponents.Input,
  },
});
State actions (
setState
, 
pushState
, 
removeState
) are built into the React schema and handled by 
ActionProvider
automatically. No need to declare them.
从标准定义中挑选你需要的组件，不要全量导入所有定义——显式选择你的应用实际使用的组件：
typescript
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
import { defineRegistry } from "@json-render/react";
import { shadcnComponents } from "@json-render/shadcn";

// Catalog: pick definitions
const catalog = defineCatalog(schema, {
  components: {
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,
    Heading: shadcnComponentDefinitions.Heading,
    Button: shadcnComponentDefinitions.Button,
    Input: shadcnComponentDefinitions.Input,
  },
  actions: {},
});

// Registry: pick matching implementations
const { registry } = defineRegistry(catalog, {
  components: {
    Card: shadcnComponents.Card,
    Stack: shadcnComponents.Stack,
    Heading: shadcnComponents.Heading,
    Button: shadcnComponents.Button,
    Input: shadcnComponents.Input,
  },
});
状态操作（
setState
、
pushState
、
removeState
）已内置到React schema中，会由
ActionProvider
自动处理，无需额外声明。

Extending with Custom Components

自定义组件扩展

Add custom components alongside standard ones:
typescript
const catalog = defineCatalog(schema, {
  components: {
    // Standard
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,

    // Custom
    Metric: {
      props: z.object({
        label: z.string(),
        value: z.string(),
        trend: z.enum(["up", "down", "neutral"]).nullable(),
      }),
      description: "KPI metric display",
    },
  },
  actions: {},
});

const { registry } = defineRegistry(catalog, {
  components: {
    Card: shadcnComponents.Card,
    Stack: shadcnComponents.Stack,
    Metric: ({ props }) => <div>{props.label}: {props.value}</div>,
  },
});
你可以在标准组件的基础上添加自定义组件：
typescript
const catalog = defineCatalog(schema, {
  components: {
    // Standard
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,

    // Custom
    Metric: {
      props: z.object({
        label: z.string(),
        value: z.string(),
        trend: z.enum(["up", "down", "neutral"]).nullable(),
      }),
      description: "KPI metric display",
    },
  },
  actions: {},
});

const { registry } = defineRegistry(catalog, {
  components: {
    Card: shadcnComponents.Card,
    Stack: shadcnComponents.Stack,
    Metric: ({ props }) => <div>{props.label}: {props.value}</div>,
  },
});

Available Components

可用组件

Layout

布局

  • Card - Container with optional title, description, maxWidth, centered
  • Stack - Flex container with direction, gap, align, justify
  • Grid - Grid layout with columns (number) and gap
  • Separator - Visual divider with orientation
  • Card - 带可选标题、描述、最大宽度、居中属性的容器
  • Stack - 支持方向、间距、对齐、对齐方式设置的Flex容器
  • Grid - 支持列数和间距设置的网格布局
  • Separator - 可设置方向的视觉分隔线

Navigation

导航

  • Tabs - Tabbed navigation with tabs array, defaultValue, value
  • Accordion - Collapsible sections with items array and type (single/multiple)
  • Collapsible - Single collapsible section with title
  • Pagination - Page navigation with totalPages and page
  • Tabs - 标签页导航，支持标签数组、默认值、当前值设置
  • Accordion - 折叠面板，支持条目数组和展开类型（单选/多选）设置
  • Collapsible - 单个可折叠区块，支持标题设置
  • Pagination - 分页导航，支持总页数和当前页设置

Overlay

浮层

  • Dialog - Modal dialog with title, description, openPath
  • Drawer - Bottom drawer with title, description, openPath
  • Tooltip - Hover tooltip with content and text
  • Popover - Click-triggered popover with trigger and content
  • DropdownMenu - Dropdown with label and items array
  • Dialog - 模态弹窗，支持标题、描述、打开路径设置
  • Drawer - 底部抽屉，支持标题、描述、打开路径设置
  • Tooltip - hover触发的提示框，支持内容和文本设置
  • Popover - 点击触发的弹出层，支持触发器和内容设置
  • DropdownMenu - 下拉菜单，支持标签和条目数组设置

Content

内容

  • Heading - Heading text with level (h1-h4)
  • Text - Paragraph with variant (body, caption, muted, lead, code)
  • Image - Image with alt, width, height
  • Avatar - User avatar with src, name, size
  • Badge - Status badge with text and variant (default, secondary, destructive, outline)
  • Alert - Alert banner with title, message, type (success, warning, info, error)
  • Carousel - Scrollable carousel with items array
  • Table - Data table with columns (string[]) and rows (string[][])
  • Heading - 标题文本，支持层级（h1-h4）设置
  • Text - 段落文本，支持变体（正文、说明文字、弱化文本、引导文本、代码）设置
  • Image - 图片，支持替代文本、宽度、高度设置
  • Avatar - 用户头像，支持图片地址、名称、尺寸设置
  • Badge - 状态徽章，支持文本和变体（默认、次要、危险、描边）设置
  • Alert - 警告横幅，支持标题、消息、类型（成功、警告、提示、错误）设置
  • Carousel - 可滚动轮播，支持条目数组设置
  • Table - 数据表格，支持列（字符串数组）和行（二维字符串数组）设置

Feedback

反馈

  • Progress - Progress bar with value, max, label
  • Skeleton - Loading placeholder with width, height, rounded
  • Spinner - Loading spinner with size and label
  • Progress - 进度条，支持当前值、最大值、标签设置
  • Skeleton - 加载占位符，支持宽度、高度、圆角设置
  • Spinner - 加载spinner，支持尺寸和标签设置

Input

输入

  • Button - Button with label, variant (primary, secondary, danger), disabled
  • Link - Anchor link with label and href
  • Input - Text input with label, name, type, placeholder, value, checks
  • Textarea - Multi-line input with label, name, placeholder, rows, value, checks
  • Select - Dropdown select with label, name, options (string[]), value, checks
  • Checkbox - Checkbox with label, name, checked, checks, validateOn
  • Radio - Radio group with label, name, options (string[]), value, checks, validateOn
  • Switch - Toggle switch with label, name, checked, checks, validateOn
  • Slider - Range slider with label, min, max, step, value
  • Toggle - Toggle button with label, pressed, variant
  • ToggleGroup - Group of toggles with items, type, value
  • ButtonGroup - Button group with buttons array and selected
  • Button - 按钮，支持标签、变体（主要、次要、危险）、禁用状态设置
  • Link - 锚点链接，支持标签和跳转地址设置
  • Input - 文本输入框，支持标签、名称、类型、占位符、值、校验规则设置
  • Textarea - 多行输入框，支持标签、名称、占位符、行数、值、校验规则设置
  • Select - 下拉选择器，支持标签、名称、选项（字符串数组）、值、校验规则设置
  • Checkbox - 复选框，支持标签、名称、选中状态、校验规则、校验触发时机设置
  • Radio - 单选框组，支持标签、名称、选项（字符串数组）、值、校验规则、校验触发时机设置
  • Switch - 开关，支持标签、名称、选中状态、校验规则、校验触发时机设置
  • Slider - 滑块，支持标签、最小值、最大值、步长、值设置
  • Toggle - 切换按钮，支持标签、按下状态、变体设置
  • ToggleGroup - 切换按钮组，支持条目、类型、值设置
  • ButtonGroup - 按钮组，支持按钮数组和选中状态设置

Built-in Actions (from 
@json-render/react
)

内置操作（来自
@json-render/react
）

These are built into the React schema and handled by 
ActionProvider
automatically. They appear in prompts without needing to be declared in the catalog.
  • setState - Set a value at a state path (
    { statePath, value }
    )
  • pushState - Push a value onto an array (
    { statePath, value, clearStatePath? }
    )
  • removeState - Remove an array item by index (
    { statePath, index }
    )
  • validateForm - Validate all fields, write 
    { valid, errors }
    to state (
    { statePath? }
    )
这些操作已内置到React schema中，会由
ActionProvider
自动处理，无需在目录中声明即可在提示中使用。
  • setState - 给指定状态路径设置值（
    { statePath, value }
    ）
  • pushState - 向数组中推入值（
    { statePath, value, clearStatePath? }
    ）
  • removeState - 按索引移除数组中的条目（
    { statePath, index }
    ）
  • validateForm - 校验所有字段，将
    { valid, errors }
    写入状态（
    { statePath? }
    ）

Validation Timing (
validateOn
)

校验时机（
validateOn
）

All form components support 
validateOn
to control when validation runs:
  • "change"
    — validate on every input change (default for Select, Checkbox, Radio, Switch)
  • "blur"
    — validate when field loses focus (default for Input, Textarea)
  • "submit"
    — validate only on form submission
所有表单组件都支持
validateOn
属性来控制校验的触发时机：
  • "change"
    — 每次输入变更时校验（Select、Checkbox、Radio、Switch的默认值）
  • "blur"
    — 字段失去焦点时校验（Input、Textarea的默认值）
  • "submit"
    — 仅在表单提交时校验

Important Notes

重要注意事项

  • The 
    /catalog
    entry point has no React dependency -- use it for server-side prompt generation
  • Components use Tailwind CSS classes -- your app must have Tailwind configured
  • Component implementations use bundled shadcn/ui primitives (not your app's 
    components/ui/
    )
  • All form inputs support 
    checks
    for validation (type + message pairs) and 
    validateOn
    for timing
  • Events: inputs emit 
    change
    /
    submit
    /
    focus
    /
    blur
    ; buttons emit 
    press
    ; selects emit 
    change
    /
    select
  • /catalog
    入口没有React依赖——可用于服务端提示生成
  • 组件使用Tailwind CSS类名——你的应用必须配置好Tailwind
  • 组件实现使用了打包好的shadcn/ui基础组件（而非你应用的
    components/ui/
    目录下的组件）
  • 所有表单输入都支持用于校验的
    checks
    属性（类型+消息对）和控制校验时机的
    validateOn
    属性
  • 事件：输入框会触发
    change
    /
    submit
    /
    focus
    /
    blur
    事件；按钮会触发
    press
    事件；选择器会触发
    change
    /
    select
    事件