import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import {Field 把标签、控件、辅助说明和错误信息收进一个对齐的区块,并可借助 FieldGroup 与 FieldSet 扩展成分组分区。底层没有基元——就是原生 fieldset、legend 以及 role="group" 语义,再与 Label 和 Separator 组合;整体按新粗野主义配方处理:图例与标签用加粗标题字体,被包裹的控件则带上粗边框与硬阴影。
适合以下场景:
- 设置页——用
FieldSet图例堆叠资料、通知、账单等分区,组间用FieldSeparator分隔。 - 结算与注册表单——在输入框、选择器与开关之间保持标签、描述和错误的对齐一致。
- 选项卡片——把单选、复选或开关包进可选中的
FieldLabel卡片,用于套餐选择与偏好面板。
安装#
pnpm dlx shadcn@latest add https://neobrutalism.com/r/base/field.jsonnpx shadcn@latest add https://neobrutalism.com/r/base/field.jsonyarn dlx shadcn@latest add https://neobrutalism.com/r/base/field.jsonbunx --bun shadcn@latest add https://neobrutalism.com/r/base/field.json
将以下代码复制并粘贴到您的项目中。
"use client"
import { useMemo } from "react"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"
import { Label } from "@/components/ui/label"
import { Separator } from "@/components/ui/separator"
function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
return (
<fieldset
data-slot="field-set"
className={cn(
"flex flex-col gap-4 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3",
className
)}
{...props}
/>
)
}
function FieldLegend({
className,
variant = "legend",
...props
}: React.ComponentProps<"legend"> & { variant?: "legend" | "label" }) {
return (
<legend
data-slot="field-legend"
data-variant={variant}
className={cn(
"mb-1.5 font-head font-medium data-[variant=label]:text-sm data-[variant=legend]:text-base",
className
)}
{...props}
/>
)
}
function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="field-group"
className={cn(
"group/field-group @container/field-group flex w-full flex-col gap-5 data-[slot=checkbox-group]:gap-3 *:data-[slot=field-group]:gap-4",
className
)}
{...props}
/>
)
}
const fieldVariants = cva(
"group/field flex w-full gap-2 data-[invalid=true]:text-destructive",
{
variants: {
orientation: {
vertical: "flex-col *:w-full [&>.sr-only]:w-auto",
horizontal:
"flex-row items-center has-[>[data-slot=field-content]]:items-start *:data-[slot=field-label]:flex-auto has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
responsive:
"flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:*:data-[slot=field-label]:flex-auto [&>.sr-only]:w-auto @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
},
},
defaultVariants: {
orientation: "vertical",
},
}
)
function Field({
className,
orientation = "vertical",
...props
}: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>) {
return (
<div
role="group"
data-slot="field"
data-orientation={orientation}
className={cn(fieldVariants({ orientation }), className)}
{...props}
/>
)
}
function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="field-content"
className={cn(
"group/field-content flex flex-1 flex-col gap-0.5 leading-snug",
className
)}
{...props}
/>
)
}
function FieldLabel({
className,
...props
}: React.ComponentProps<typeof Label>) {
return (
<Label
data-slot="field-label"
className={cn(
"group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50 has-data-checked:border-primary/30 has-data-checked:bg-primary/5 has-[>[data-slot=field]]:rounded has-[>[data-slot=field]]:border-2 *:data-[slot=field]:p-2.5 dark:has-data-checked:border-primary/20 dark:has-data-checked:bg-primary/10",
"has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col",
className
)}
{...props}
/>
)
}
function FieldTitle({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="field-label"
className={cn(
"flex w-fit items-center gap-2 text-sm font-head font-medium group-data-[disabled=true]/field:opacity-50",
className
)}
{...props}
/>
)
}
function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
return (
<p
data-slot="field-description"
className={cn(
"text-left text-sm leading-normal font-normal text-muted-foreground group-has-data-horizontal/field:text-balance [[data-variant=legend]+&]:-mt-1.5",
"last:mt-0 nth-last-2:-mt-1",
"[&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
className
)}
{...props}
/>
)
}
function FieldSeparator({
children,
className,
...props
}: React.ComponentProps<"div"> & {
children?: React.ReactNode
}) {
return (
<div
data-slot="field-separator"
data-content={!!children}
className={cn(
"relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2",
className
)}
{...props}
>
<Separator className="absolute inset-0 top-1/2" />
{children && (
<span
className="relative mx-auto block w-fit bg-background px-2 text-muted-foreground"
data-slot="field-separator-content"
>
{children}
</span>
)}
</div>
)
}
function FieldError({
className,
children,
errors,
...props
}: React.ComponentProps<"div"> & {
errors?: Array<{ message?: string } | undefined>
}) {
const content = useMemo(() => {
if (children) {
return children
}
if (!errors?.length) {
return null
}
const uniqueErrors = [
...new Map(errors.map((error) => [error?.message, error])).values(),
]
if (uniqueErrors?.length == 1) {
return uniqueErrors[0]?.message
}
return (
<ul className="ml-4 flex list-disc flex-col gap-1">
{uniqueErrors.map(
(error, index) =>
error?.message && <li key={index}>{error.message}</li>
)}
</ul>
)
}, [children, errors])
if (!content) {
return null
}
return (
<div
role="alert"
data-slot="field-error"
className={cn("text-sm font-normal text-destructive", className)}
{...props}
>
{content}
</div>
)
}
export {
Field,
FieldLabel,
FieldDescription,
FieldError,
FieldGroup,
FieldLegend,
FieldSeparator,
FieldSet,
FieldContent,
FieldTitle,
}
更新导入路径以匹配您的项目结构。
用法#
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
├── Input / Textarea / Switch / Select
├── FieldDescription
└── FieldErrorFieldGroup#
将相关字段归入同一分组。必要时在各区块之间插入 FieldSeparator。
FieldGroup
├── Field
│ ├── FieldLabel
│ ├── Input / Textarea / Switch / Select
│ ├── FieldDescription
│ └── FieldError
├── FieldSeparator
└── Field
├── FieldLabel
└── Input / Textarea / Switch / SelectFieldSet#
带有说明性标题和描述的语义化分组,通常包含一个 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">Label</FieldLabel>
{/* Input, Select, Switch, etc. */}
<FieldDescription>Optional helper text.</FieldDescription>
<FieldError>Validation message.</FieldError>
</Field>Field是单个字段的核心包装器。FieldContent是一个用于将标签和说明组合在一起的 flex 列。如果没有说明,则无需使用。- 用
FieldGroup包裹相关字段,并使用FieldSet搭配FieldLegend进行语义化分组。
表单#
有关使用 Field 组件以及 React Hook Form、Tanstack Form 或 Formisch 构建表单的方法,请参阅 Form 文档。
示例#
Input#
import {
Field,
FieldDescription,Textarea#
import {
Field,
FieldDescription,Select#
import {
Field,
FieldDescription,Slider#
"use client"
import * as React from "react"Fieldset#
import {
Field,
FieldDescription,Checkbox#
import { Checkbox } from "@/components/ui/checkbox"
import {
Field,Radio#
import {
Field,
FieldDescription,Switch#
import { Field, FieldLabel } from "@/components/ui/field"
import { Switch } from "@/components/ui/switch"
选择卡片#
用 FieldLabel 包裹 Field 组件,即可创建可选择的字段组。这适用于 RadioItem、Checkbox 和 Switch 组件。
import {
Field,
FieldContent,字段组#
用 FieldGroup 将 Field 组件堆叠排列。添加 FieldSeparator 来分隔它们。
import { Checkbox } from "@/components/ui/checkbox"
import {
Field,RTL#
若要在 Neobrutalism 中启用 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">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,以确保屏幕阅读器能识别清晰的区块边界。
无障碍#
Field 系列以语义优先:FieldSet 与 FieldLegend 渲染原生 fieldset/legend,Field 渲染 role="group",FieldError 渲染 role="alert",于是校验信息一出现就会被播报。
- 通过
htmlFor/id把每个FieldLabel与控件配对——点击标签会聚焦控件,屏幕阅读器也会读出关联关系。 - 输入无效时,在控件本身设置
aria-invalid;Field上的data-invalid只驱动错误样式。 - 键盘行为属于内部控件——包装层自身不增加焦点停靠点或按键绑定。
API 参考#
FieldSet#
渲染带有预设间距的语义化 fieldset 的容器。
| Prop | Type | Default |
|---|---|---|
className | string |
<FieldSet>
<FieldLegend>Delivery</FieldLegend>
<FieldGroup>{/* Fields */}</FieldGroup>
</FieldSet>FieldLegend#
FieldSet 的标题元素。切换为 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 列。如果没有说明,则无需使用。
| 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#
同时适用于直接输入控件和嵌套 Field 子元素的样式化标签。
| Prop | Type | Default |
|---|---|---|
className | string | |
asChild | boolean | false |
<FieldLabel htmlFor="email">Email</FieldLabel>FieldTitle#
在 FieldContent 内部渲染一个采用标签样式的标题。
| Prop | Type | Default |
|---|---|---|
className | string |
<FieldContent>
<FieldTitle>Enable Touch ID</FieldTitle>
<FieldDescription>Unlock your device faster.</FieldDescription>
</FieldContent>FieldDescription#
帮助文本插槽,会在横向布局中自动平衡较长的行。
| Prop | Type | Default |
|---|---|---|
className | string |
<FieldDescription>We never share your email with anyone.</FieldDescription>FieldSeparator#
用于在 FieldGroup 内部分隔各区块的视觉分隔线。可选择性地接受内联内容。
| Prop | Type | Default |
|---|---|---|
className | string |
<FieldSeparator>Or continue with</FieldSeparator>FieldError#
无障碍的错误容器,接受子元素或一个 errors 数组(例如来自 react-hook-form)。
| Prop | Type | Default |
|---|---|---|
errors | Array<{ message?: string } | undefined> | |
className | string |
<FieldError errors={errors.username} />当 errors 数组包含多条消息时,组件会自动渲染为列表。
FieldError 还接受任何实现了 Standard Schema 的校验器所生成的 issue,包括 Zod、Valibot 和 ArkType。直接将 schema 结果中的 issues 数组传入,即可跨库渲染统一的错误列表。