介绍

开始使用

表单

注册表

字段 Field

结合标签、控件和帮助文本，以组成可访问的表单字段和分组输入。

import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import {

安装


pnpm dlx shadcn@latest add field

用法

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
  FieldTitle,
} from "@/components/ui/field"

<FieldSet>
  <FieldLegend>个人资料</FieldLegend>
  <FieldDescription>此信息将显示在发票和邮件中。</FieldDescription>
  <FieldGroup>
    <Field>
      <FieldLabel htmlFor="name">全名</FieldLabel>
      <Input id="name" autoComplete="off" placeholder="邪恶兔子" />
      <FieldDescription>此信息将显示在发票和邮件中。</FieldDescription>
    </Field>
    <Field>
      <FieldLabel htmlFor="username">用户名</FieldLabel>
      <Input id="username" autoComplete="off" aria-invalid />
      <FieldError>请选择其他用户名。</FieldError>
    </Field>
    <Field orientation="horizontal">
      <Switch id="newsletter" />
      <FieldLabel htmlFor="newsletter">订阅新闻通讯</FieldLabel>
    </Field>
  </FieldGroup>
</FieldSet>

结构解析

Field 组件族用于组合无障碍的表单。一个典型的字段结构如下：

<Field>
  <FieldLabel htmlFor="input-id">标签</FieldLabel>
  {/* 输入框、选择框、开关等控件 */}
  <FieldDescription>可选的辅助说明文本。</FieldDescription>
  <FieldError>校验信息。</FieldError>
</Field>

Field 是单个字段的核心容器。
FieldContent 是一个 flex 列，用于分组标签和描述。如果没有描述，可不使用。
相关字段可用 FieldGroup 包裹，并用 FieldSet 和 FieldLegend 做语义分组。

表单集成

查看表单文档，了解如何结合 Field 组件与 React Hook Form 或 Tanstack Form 构建表单。

示例

输入框

import {
  Field,
  FieldDescription,

多行文本框

import {
  Field,
  FieldDescription,

选择框

import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import {
  Select,

滑块

"use client"

import * as React from "react"

字段集

Address Information

We need your address to deliver your order.

import {
  Field,
  FieldDescription,

复选框

Show these items on the desktop

Select the items you want to show on the desktop.

Hard disks

External disks

CDs, DVDs, and iPods

Connected servers

Sync Desktop & Documents folders

Your Desktop & Documents folders are being synced with iCloud Drive. You can access them from other devices.

import { Checkbox } from "@/components/ui/checkbox"
import {
  Field,

单选框

Subscription Plan

Yearly and lifetime plans offer significant savings.

Monthly ($9.99/month)

Yearly ($99.99/year)

Lifetime ($299.99)

import {
  Field,
  FieldDescription,

开关

Multi-factor authentication

import { Field, FieldLabel } from "@/components/ui/field"
import { Switch } from "@/components/ui/switch"

选择卡片

将多个 Field 组件包裹于 FieldLabel 中，创建可选择的字段组。支持与 RadioItem、Checkbox 和 Switch 组件搭配使用。

Compute Environment

Select the compute environment for your cluster.

Kubernetes

Run GPU workloads on a K8s cluster.

Virtual Machine

Access a cluster to run GPU workloads.

import {
  Field,
  FieldContent,

字段组

使用 FieldGroup 堆叠多个 Field 组件。添加 FieldSeparator 用以分隔。

Responses

Get notified when ChatGPT responds to requests that take time, like research or image generation.

Push notifications

Tasks

Get notified when tasks you've created have updates. Manage tasks

Push notifications

Email notifications

import { Checkbox } from "@/components/ui/checkbox"
import {
  Field,

响应式布局

垂直字段: 默认方向是标签、控件和辅助文本垂直堆叠，适合移动优先布局。
水平字段: 在 Field 上设置 orientation="horizontal"，使标签和控件并排。配合 FieldContent 保持描述对齐。
响应式字段: 设为 orientation="responsive"，在容器感知的父元素内自动切换列布局。在 FieldGroup 上添加 @container/field-group 类，可在特定断点切换方向。

import { Button } from "@/components/ui/button"
import {
  Field,

验证与错误提示

在 Field 上添加 data-invalid，将整个块切换为错误状态。
在输入控件本身添加 aria-invalid，增强辅助技术支持。
将 FieldError 渲染在控件后面或放入 FieldContent，保持错误信息与字段对齐。

<Field data-invalid>
  <FieldLabel htmlFor="email">电子邮箱</FieldLabel>
  <Input id="email" type="email" aria-invalid />
  <FieldError>请输入有效的电子邮箱地址。</FieldError>
</Field>

无障碍支持

FieldSet 和 FieldLegend 用于将相关控件分组，便于键盘和辅助技术用户操作。
Field 输出 role="group"，嵌套控件可继承来自 FieldLabel 和 FieldLegend 的标签。
谨慎使用 FieldSeparator，保证屏幕阅读器识别清晰的区域边界。

API 参考

FieldSet

语义容器，渲染 fieldset，带有预设间距。

属性	类型	默认值
`className`	`string`

<FieldSet>
  <FieldLegend>递送信息</FieldLegend>
  <FieldGroup>{/* 字段们 */}</FieldGroup>
</FieldSet>

FieldLegend

FieldSet 的标题元素。切换到 label 变体可以配合标签大小对齐。

属性	类型	默认值
`variant`	`"legend" \| "label"`	`"legend"`
`className`	`string`

<FieldLegend variant="label">通知偏好</FieldLegend>

FieldLegend 有两个变体：legend 和 label。label 变体应用标签大小和对齐，适用于嵌套的 FieldSet。

FieldGroup

布局容器，堆叠 Field 组件并支持响应式容器查询。

属性	类型	默认值
`className`	`string`

<FieldGroup className="@container/field-group flex flex-col gap-6">
  <Field>{/* ... */}</Field>
  <Field>{/* ... */}</Field>
</FieldGroup>

Field

单个字段的核心外壳。提供方向控制、无效态样式和间距。

属性	类型	默认值
`orientation`	`"vertical" \| "horizontal" \| "responsive"`	`"vertical"`
`className`	`string`
`data-invalid`	`boolean`

<Field orientation="horizontal">
  <FieldLabel htmlFor="remember">记住我</FieldLabel>
  <Switch id="remember" />
</Field>

FieldContent

flex 列，用于标签旁边含描述时分组控件和说明。无说明时可不使用。

属性	类型	默认值
`className`	`string`

<Field>
  <Checkbox id="notifications" />
  <FieldContent>
    <FieldLabel htmlFor="notifications">通知</FieldLabel>
    <FieldDescription>邮箱、短信及推送选项。</FieldDescription>
  </FieldContent>
</Field>

FieldLabel

标签，适用于直接输入控件或嵌套 Field 的子元素。

属性	类型	默认值
`className`	`string`
`asChild`	`boolean`	`false`

<FieldLabel htmlFor="email">电子邮箱</FieldLabel>

FieldTitle

在 FieldContent 内渲染带标签样式的标题。

属性	类型	默认值
`className`	`string`

<FieldContent>
  <FieldTitle>启用 Touch ID</FieldTitle>
  <FieldDescription>更快解锁设备。</FieldDescription>
</FieldContent>

FieldDescription

辅助文本槽，在水平布局中自动平衡长行。

属性	类型	默认值
`className`	`string`

<FieldDescription>我们绝不向他人泄露您的邮箱。</FieldDescription>

FieldSeparator

视视觉分隔线，用于 FieldGroup 内部分割区块。可接受内联内容。

属性	类型	默认值
`className`	`string`

<FieldSeparator>或继续使用</FieldSeparator>

FieldError

无障碍错误容器，支持子节点或 errors 数组（例如来自 react-hook-form）。

属性	类型	默认值
`errors`	`Array<{ message?: string } \| undefined>`
`className`	`string`

<FieldError errors={errors.username} />

当 errors 数组包含多条消息时，组件会自动渲染列表。

FieldError 也支持任何实现了标准 Schema 的验证器生成的问题数组，如 Zod、Valibot 和 ArkType。直接传入 Schema 结果中的 issues 数组即可跨库统一渲染错误列表。

空状态 Empty 悬停卡片