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>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 系列旨在帮助你组合出可访问的表单。一个典型的字段结构如下：

<Field>
  <FieldLabel htmlFor="input-id">Label</FieldLabel>
  {/* Input, Select, Switch, etc. */}
  <FieldDescription>Optional helper text.</FieldDescription>
  <FieldError>Validation message.</FieldError>
</Field>

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

表单

请参见 Form 文档，了解如何使用 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,

RTL

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

"use client"

import { Button } from "@/examples/radix/ui-rtl/button"

响应式布局

垂直字段：默认方向会将标签、控件和辅助文本堆叠起来，非常适合移动优先布局。
水平字段：在 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">Email</FieldLabel>
  <Input id="email" type="email" aria-invalid />
  <FieldError>Enter a valid email address.</FieldError>
</Field>

可访问性

FieldSet 和 FieldLegend 会把相关控件分组，方便键盘和辅助技术用户使用。
Field 会输出 role="group"，因此当和 FieldLabel、FieldLegend 组合时，嵌套控件可以继承标签语义。
请谨慎使用 FieldSeparator，以确保屏幕阅读器能够清晰感知区段边界。

API 参考

FieldSet

渲染语义化 fieldset 且带有间距预设的容器。

Prop	Type	Default
`className`	`string`

<FieldSet>
  <FieldLegend>Delivery</FieldLegend>
  <FieldGroup>{/* Fields */}</FieldGroup>
</FieldSet>

FieldLegend

FieldSet 的 legend 元素。切换到 label 变体可以与标签尺寸对齐。

Prop	Type	Default
`variant`	`"legend" \| "label"`	`"legend"`
`className`	`string`

<FieldLegend variant="label">Notification Preferences</FieldLegend>

FieldLegend 有两个变体：legend 和 label。label 变体会应用标签尺寸和对齐方式。如果你有嵌套的 FieldSet，它会很有用。

FieldGroup

一个布局包装器，用于堆叠 Field 组件，并为响应式方向启用容器查询。

Prop	Type	Default
`className`	`string`

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

Field

单个字段的核心包装器。提供方向控制、无效状态样式和间距。

Prop	Type	Default
`orientation`	`"vertical" \| "horizontal" \| "responsive"`	`"vertical"`
`className`	`string`
`data-invalid`	`boolean`

<Field orientation="horizontal">
  <FieldLabel htmlFor="remember">Remember me</FieldLabel>
  <Switch id="remember" />
</Field>

FieldContent

当标签位于控件旁边时，用于将控件和说明分组的 flex column。如果没有说明，这个组件不是必需的。

Prop	Type	Default
`className`	`string`

<Field>
  <Checkbox id="notifications" />
  <FieldContent>
    <FieldLabel htmlFor="notifications">Notifications</FieldLabel>
    <FieldDescription>Email, SMS, and push options.</FieldDescription>
  </FieldContent>
</Field>

FieldLabel

Label styled for both direct inputs and nested Field children.

Prop	Type	Default
`className`	`string`
`asChild`	`boolean`	`false`

<FieldLabel htmlFor="email">Email</FieldLabel>

FieldTitle

Renders a title with label styling inside FieldContent.

Prop	Type	Default
`className`	`string`

<FieldContent>
  <FieldTitle>Enable Touch ID</FieldTitle>
  <FieldDescription>Unlock your device faster.</FieldDescription>
</FieldContent>

FieldDescription

Helper text slot that automatically balances long lines in horizontal layouts.

Prop	Type	Default
`className`	`string`

<FieldDescription>We never share your email with anyone.</FieldDescription>

FieldSeparator

Visual divider to separate sections inside a FieldGroup. Accepts optional inline content.

Prop	Type	Default
`className`	`string`

<FieldSeparator>Or continue with</FieldSeparator>

FieldError

Accessible error container that accepts children or an errors array (e.g., from react-hook-form).

Prop	Type	Default
`errors`	`Array<{ message?: string } \| undefined>`
`className`	`string`

<FieldError errors={errors.username} />

When the errors array contains multiple messages, the component renders a list automatically.

FieldError also accepts issues produced by any validator that implements Standard Schema, including Zod, Valibot, and ArkType. Pass the issues array from the schema result directly to render a unified error list across libraries.

Empty Hover Card

用 Dory 探索你的数据

AI 驱动的 SQL 工作台，连接 Postgres / MySQL 等数据库，快速查询与分析数据。

用 AI 快速得到答案，开源且免费。