import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import {Field는 레이블, 컨트롤, 도움말, 오류 메시지를 하나의 정렬된 블록으로 묶고, FieldGroup과 FieldSet으로 섹션 단위까지 확장합니다. 하위 프리미티브는 없습니다. 네이티브 fieldset, legend, role="group" 시맨틱을 Label과 Separator와 조합하며, 범례와 레이블에는 굵은 제목 서체를, 감싸인 컨트롤에는 두꺼운 테두리와 선명한 그림자를 적용합니다.
다음과 같은 경우에 사용합니다.
- 설정 페이지 —
FieldSet범례와 그룹 사이FieldSeparator로 프로필, 알림, 결제 섹션을 쌓습니다. - 결제·가입 폼 — input, select, switch 전반에서 레이블·설명·오류 정렬을 맞춥니다.
- 선택 카드 — 플랜 선택기나 환경설정 패널에서 라디오, 체크박스, 스위치를 선택 가능한
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"
선택 카드#
Field 컴포넌트를 FieldLabel 로 감싸 선택 가능한 필드 그룹을 만듭니다. 이는 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"를 렌더링해 유효성 메시지가 나타나는 즉시 안내됩니다.
- 모든
FieldLabel을htmlFor/id로 컨트롤과 짝지으세요. 레이블 클릭이 컨트롤에 포커스하고, 스크린 리더가 연결을 읽어 줍니다. - 잘못된 입력에는 컨트롤 자체에
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#
자식 요소나 (예: react-hook-form 에서 온) errors 배열을 받는 접근성 높은 오류 컨테이너입니다.
| Prop | Type | Default |
|---|---|---|
errors | Array<{ message?: string } | undefined> | |
className | string |
<FieldError errors={errors.username} />errors 배열에 여러 메시지가 포함되면 컴포넌트가 자동으로 목록을 렌더링합니다.
FieldError 는 Zod, Valibot, ArkType 등 Standard Schema 를 구현하는 모든 검증기가 생성한 이슈도 받습니다. 스키마 결과의 issues 배열을 그대로 전달하면 라이브러리에 관계없이 통일된 오류 목록을 렌더링할 수 있습니다.