콘텐츠로 건너뛰기

필드

설정 패널, 결제 양식, 가입 절차에 사용되는 라벨, 컨트롤, 도움말 텍스트 및 오류 메시지 슬롯 — 네오브루탈리즘 양식의 디자인 기법을 적용했습니다.

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

Field는 레이블, 컨트롤, 도움말, 오류 메시지를 하나의 정렬된 블록으로 묶고, FieldGroupFieldSet으로 섹션 단위까지 확장합니다. 하위 프리미티브는 없습니다. 네이티브 fieldset, legend, role="group" 시맨틱을 LabelSeparator와 조합하며, 범례와 레이블에는 굵은 제목 서체를, 감싸인 컨트롤에는 두꺼운 테두리와 선명한 그림자를 적용합니다.

다음과 같은 경우에 사용합니다.

  • 설정 페이지FieldSet 범례와 그룹 사이 FieldSeparator로 프로필, 알림, 결제 섹션을 쌓습니다.
  • 결제·가입 폼 — input, select, switch 전반에서 레이블·설명·오류 정렬을 맞춥니다.
  • 선택 카드 — 플랜 선택기나 환경설정 패널에서 라디오, 체크박스, 스위치를 선택 가능한 FieldLabel 카드로 감쌉니다.

설치

pnpm dlx shadcn@latest add https://neobrutalism.com/r/base/field.json
npx shadcn@latest add https://neobrutalism.com/r/base/field.json
yarn dlx shadcn@latest add https://neobrutalism.com/r/base/field.json
bunx --bun shadcn@latest add https://neobrutalism.com/r/base/field.json

다음 코드를 복사해 프로젝트에 붙여넣습니다.

components/ui/field.tsx
"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
└── FieldError

FieldGroup

관련된 필드를 하나의 그룹으로 묶습니다. 필요하면 섹션 사이에 FieldSeparator 를 넣습니다.

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

FieldSet

범례와 설명을 갖춘 시맨틱 그룹으로, 보통 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 으로 묶고, 시맨틱 그룹화에는 FieldSetFieldLegend 를 사용합니다.

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"

반응형 레이아웃

  • 세로 필드: 기본 방향은 레이블, 컨트롤, 도움말 텍스트를 세로로 쌓으며, 모바일 우선 레이아웃에 적합합니다.
  • 가로 필드: Fieldorientation="horizontal" 을 설정하면 레이블과 컨트롤이 나란히 정렬됩니다. FieldContent 와 함께 사용하면 설명의 정렬을 유지할 수 있습니다.
  • 반응형 필드: 컨테이너를 인식하는 부모 요소 안에서 열 레이아웃을 자동화하려면 orientation="responsive" 를 설정합니다. 특정 브레이크포인트에서 방향을 전환하려면 FieldGroup@container/field-group 클래스를 적용합니다.
import { Button } from "@/components/ui/button"
import {
  Field,

검증과 오류

  • Fielddata-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>

접근성

  • FieldSetFieldLegend 는 키보드나 보조 기술을 사용하는 사람을 위해 관련 컨트롤을 그룹으로 유지합니다.
  • Fieldrole="group" 을 출력하므로, 조합했을 때 중첩된 컨트롤이 FieldLabelFieldLegend 의 레이블링을 상속합니다.
  • 스크린 리더가 명확한 섹션 경계를 인식할 수 있도록 FieldSeparator 는 절제해서 사용합니다.

접근성

Field 계열은 시맨틱을 우선합니다. FieldSetFieldLegend는 네이티브 fieldset/legend를, Fieldrole="group"을, FieldErrorrole="alert"를 렌더링해 유효성 메시지가 나타나는 즉시 안내됩니다.

  • 모든 FieldLabelhtmlFor/id로 컨트롤과 짝지으세요. 레이블 클릭이 컨트롤에 포커스하고, 스크린 리더가 연결을 읽어 줍니다.
  • 잘못된 입력에는 컨트롤 자체에 aria-invalid를 두세요. Fielddata-invalid는 오류 스타일만 담당합니다.
  • 키보드 동작은 안의 컨트롤에 있습니다. 래퍼는 포커스 정지나 키 바인딩을 추가하지 않습니다.

API 참조

FieldSet

간격 프리셋을 갖춘 시맨틱 fieldset 을 렌더링하는 컨테이너입니다.

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

FieldLegend

FieldSet 의 범례 요소입니다. 레이블 크기에 맞추려면 label 배리언트로 전환합니다.

PropTypeDefault
variant"legend" | "label""legend"
classNamestring
<FieldLegend variant="label">Notification Preferences</FieldLegend>

FieldLegend 에는 legendlabel 두 가지 배리언트가 있습니다. label 배리언트는 레이블 크기와 정렬을 적용합니다. FieldSet 을 중첩할 때 유용합니다.

FieldGroup

Field 컴포넌트를 쌓고, 반응형 방향을 위해 컨테이너 쿼리를 활성화하는 레이아웃 래퍼입니다.

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

Field

단일 필드의 핵심 래퍼입니다. 방향 제어, 유효하지 않은 상태 스타일, 간격을 제공합니다.

PropTypeDefault
orientation"vertical" | "horizontal" | "responsive""vertical"
classNamestring
data-invalidboolean
<Field orientation="horizontal">
  <FieldLabel htmlFor="remember">Remember me</FieldLabel>
  <Switch id="remember" />
</Field>

FieldContent

레이블이 컨트롤 옆에 배치될 때 컨트롤과 설명을 묶는 flex 컬럼입니다. 설명이 없다면 필요하지 않습니다.

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

FieldLabel

직접 입력과 중첩된 Field 자식 요소 모두에 맞춰 스타일이 지정된 레이블입니다.

PropTypeDefault
classNamestring
asChildbooleanfalse
<FieldLabel htmlFor="email">Email</FieldLabel>

FieldTitle

FieldContent 안에서 레이블 스타일을 적용한 제목을 렌더링합니다.

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

FieldDescription

가로 레이아웃에서 긴 줄을 자동으로 균형 있게 맞추는 도움말 텍스트 슬롯입니다.

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

FieldSeparator

FieldGroup 안에서 섹션을 구분하는 시각적 구분선입니다. 인라인 콘텐츠를 선택적으로 받을 수 있습니다.

PropTypeDefault
classNamestring
<FieldSeparator>Or continue with</FieldSeparator>

FieldError

자식 요소나 (예: react-hook-form 에서 온) errors 배열을 받는 접근성 높은 오류 컨테이너입니다.

PropTypeDefault
errorsArray<{ message?: string } | undefined>
classNamestring
<FieldError errors={errors.username} />

errors 배열에 여러 메시지가 포함되면 컴포넌트가 자동으로 목록을 렌더링합니다.

FieldError 는 Zod, Valibot, ArkType 등 Standard Schema 를 구현하는 모든 검증기가 생성한 이슈도 받습니다. 스키마 결과의 issues 배열을 그대로 전달하면 라이브러리에 관계없이 통일된 오류 목록을 렌더링할 수 있습니다.