Back to Details

json-render-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
组件目录架构（无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架构中，由
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: {
    // 标准组件
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,

    // 自定义组件
    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 - 弹性布局容器，支持方向、间距、对齐、内容分布属性
  • 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 - 悬停提示框，支持内容和文本属性
  • 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 - 图片组件，支持alt、宽度、高度属性
  • Avatar - 用户头像组件，支持src、名称、尺寸属性
  • 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 - 加载动画，支持尺寸和标签属性

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
  • Radio - Radio group with label, name, options (string[]), value
  • Switch - Toggle switch with label, name, checked
  • 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 - 锚点链接，支持标签和href属性
  • 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 }
    )
这些操作已内置到React架构中，由
ActionProvider
自动处理。无需在组件目录中声明即可在提示中使用。
  • setState - 在指定状态路径设置值（参数：
    { statePath, value }
    ）
  • pushState - 向数组状态中添加值（参数：
    { statePath, value, clearStatePath? }
    ）
  • removeState - 根据索引移除数组中的项（参数：
    { statePath, index }
    ）

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/
    )
  • Form inputs support 
    checks
    for validation (type + message pairs)
  • Events: inputs emit 
    change
    /
    submit
    /
    focus
    /
    blur
    ; buttons emit 
    press
    ; selects emit 
    change
    /
    select
  • /catalog
    入口点无React依赖——可用于服务端提示生成
  • 组件使用Tailwind CSS类——你的应用必须配置Tailwind CSS
  • 组件实现使用打包后的shadcn/ui原语（而非你的应用中的
    components/ui/
    ）
  • 表单输入支持
    checks
    属性用于校验（类型+消息对）
  • 事件：输入框触发
    change
    /
    submit
    /
    focus
    /
    blur
    事件；按钮触发
    press
    事件；选择框触发
    change
    /
    select
    事件