字段

组合标签、控件和帮助文本，构建无障碍表单字段和分组输入。

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>Profile</FieldLegend>
  <FieldDescription>This appears on invoices and emails.</FieldDescription>
  <FieldGroup>
    <Field>
      <FieldLabel htmlFor="name">Full name</FieldLabel>
      <Input id="name" autoComplete="off" placeholder="Evil Rabbit" />
      <FieldDescription>This appears on invoices and emails.</FieldDescription>
    </Field>
    <Field>
      <FieldLabel htmlFor="username">Username</FieldLabel>
      <Input id="username" autoComplete="off" aria-invalid />
      <FieldError>Choose another username.</FieldError>
    </Field>
    <Field orientation="horizontal">
      <Switch id="newsletter" />
      <FieldLabel htmlFor="newsletter">Subscribe to the newsletter</FieldLabel>
    </Field>
  </FieldGroup>
</FieldSet>

组合

字段

带有标签、辅助文本和验证信息的单个控件。

Field
├── FieldLabel
├── Input / Textarea / Switch / Select
├── FieldDescription
└── FieldError

字段组

一组相关字段。需要时，在各个部分之间使用 FieldSeparator。

FieldGroup
├── Field
│   ├── FieldLabel
│   ├── Input / Textarea / Switch / Select
│   ├── FieldDescription
│   └── FieldError
├── FieldSeparator
└── Field
    ├── FieldLabel
    └── Input / Textarea / Switch / Select

字段集

使用图例和描述进行语义分组，通常包含一个 FieldGroup。

FieldSet
├── FieldLegend
├── FieldDescription
└── FieldGroup
    ├── Field
    │   ├── FieldLabel
    │   ├── Input / Textarea / Switch / Select
    │   ├── FieldDescription
    │   └── FieldError
    └── Field
        ├── FieldLabel
        └── Input / Textarea / Switch / Select

结构

Field 系列组件用于组合构建无障碍表单。典型字段的结构如下：

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

Field 是单个字段的核心包装器。
FieldContent 是用于将标签和描述分组的弹性列布局。如果没有描述，则不需要使用它。
使用 FieldGroup 包装相关字段，并将 FieldSet 与 FieldLegend 结合使用以实现语义分组。

表单

请参阅表单文档，了解如何使用 Field 组件以及 React Hook Form、Tanstack Form 或 Formisch 构建表单。

输入

import {
  Field,
  FieldDescription,

文本域

import {
  Field,
  FieldDescription,

选择

import {
  Field,
  FieldDescription,

滑块

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

RTL

要在 shadcn/ui 中启用 RTL 支持，请参阅 RTL 配置指南。

"use client"

import * as React from "react"

响应式布局

垂直字段： 默认方向将标签、控件和辅助文本垂直堆叠—非常适合移动优先布局。
水平字段： 在 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`

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

FieldTitle

在 FieldContent 中以标签样式渲染标题。

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

<FieldContent>
  <FieldTitle>启用触控 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 也接受由任何实现了 Standard Schema 的验证器生成的问题，包括 Zod、Valibot 和 ArkType。直接将架构结果中的 issues 数组传入，即可在不同库之间渲染统一的错误列表。

空状态输入框