Field
라벨, 컨트롤, 설명 텍스트를 조합하여 접근성 있는 폼 필드를 구성하는 컴포넌트
개요
Field 컴포넌트 패밀리는 접근성 있는 폼을 구성하기 위한 컴파운드 컴포넌트입니다. 단일 필드부터 복잡한 폼 레이아웃까지 유연하게 조합할 수 있습니다.
주요 특징
- ✅ 컴파운드 컴포넌트: 10개의 서브 컴포넌트로 유연한 폼 구성
- ✅ 레이아웃 제어: vertical, horizontal, responsive 방향 지원
- ✅ 유효성 검증: FieldError를 통한 에러 메시지 표시
- ✅ 접근성:
<fieldset>,role="group"등 시맨틱 마크업 자동 적용 - ✅ 디자인 토큰: 테마 커스터마이징 지원
구조 (Anatomy)
<FieldSet>
<FieldLegend>그룹 제목</FieldLegend>
<FieldDescription>그룹 설명</FieldDescription>
<FieldGroup>
<Field>
<FieldLabel htmlFor="input-id">라벨</FieldLabel>
{/* Input, Select, Switch 등 */}
<FieldDescription>도움말 텍스트</FieldDescription>
<FieldError>유효성 검증 메시지</FieldError>
</Field>
</FieldGroup>
</FieldSet>사용 예시
기본 입력 필드
라벨과 설명이 포함된 기본 형태입니다.
Preview
계정에 사용될 고유한 이름입니다.
에러 상태
data-invalid 속성과 FieldError로 유효성 검증 상태를 표시합니다.
Preview
Horizontal 레이아웃
orientation="horizontal"로 라벨과 컨트롤을 가로로 배치합니다.
Preview
서비스 이용약관에 동의합니다.
FieldSet과 FieldGroup
관련 필드들을 시맨틱하게 그룹화합니다.
Preview
FieldSeparator
FieldGroup 내부에서 섹션을 구분합니다.
Preview
새로운 소식을 이메일로 받습니다.
브라우저 푸시 알림을 받습니다.
API Reference
Field
단일 필드의 핵심 래퍼입니다. 방향 제어, 유효 상태 스타일링, 간격을 제공합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
orientation | "vertical" | "horizontal" | "responsive" | "vertical" | 레이아웃 방향 |
data-invalid | boolean | - | 에러 상태 표시 |
className | string | - | 추가 CSS 클래스 |
FieldSet
시맨틱 <fieldset>을 렌더링하는 컨테이너입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
FieldLegend
FieldSet의 <legend> 요소입니다. label variant로 라벨 크기에 맞출 수 있습니다.
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "legend" | "label" | "legend" | 텍스트 크기 |
className | string | - | 추가 CSS 클래스 |
FieldGroup
Field 컴포넌트를 쌓아 배치하는 레이아웃 래퍼입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
FieldContent
라벨과 설명을 그룹화하는 flex column 컨테이너입니다. horizontal 레이아웃에서 라벨과 설명을 정렬할 때 사용합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
FieldLabel
입력 요소와 연결되는 라벨 컴포넌트입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
htmlFor | string | - | 연결할 입력 요소 ID |
className | string | - | 추가 CSS 클래스 |
FieldTitle
FieldContent 내부에서 라벨 스타일의 제목을 렌더링합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
FieldDescription
도움말 텍스트를 표시합니다. horizontal 레이아웃에서 자동으로 텍스트 밸런싱을 적용합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
FieldSeparator
FieldGroup 내부에서 섹션을 구분하는 시각적 구분선입니다. 인라인 콘텐츠를 포함할 수 있습니다.
| Prop | Type | Default | Description |
|---|---|---|---|
children | React.ReactNode | - | 구분선 내부 텍스트 |
className | string | - | 추가 CSS 클래스 |
FieldError
에러 메시지를 표시합니다. children 또는 errors 배열을 받을 수 있습니다.
| Prop | Type | Default | Description |
|---|---|---|---|
children | React.ReactNode | - | 직접 에러 메시지 지정 |
errors | Array<{ message?: string } | undefined> | - | 에러 객체 배열 (react-hook-form 등) |
className | string | - | 추가 CSS 클래스 |
기본 사용법
import {
Field,
FieldSet,
FieldLegend,
FieldGroup,
FieldContent,
FieldLabel,
FieldTitle,
FieldDescription,
FieldSeparator,
FieldError,
} from "@vortex/ui-foundation"
;<Field>
<FieldLabel htmlFor="name">이름</FieldLabel>
<Input id="name" />
<FieldDescription>표시될 이름입니다.</FieldDescription>
</Field>접근성
시맨틱 마크업
FieldSet→<fieldset>,FieldLegend→<legend>으로 관련 컨트롤을 시맨틱하게 그룹화Field→role="group"적용으로 라벨링 상속FieldError→role="alert"적용으로 스크린 리더에 에러 즉시 전달
유효성 검증
// data-invalid으로 필드 전체를 에러 상태로 전환
// aria-invalid으로 보조 기술에 에러 상태 전달
<Field data-invalid>
<FieldLabel htmlFor="email">이메일</FieldLabel>
<Input id="email" aria-invalid />
<FieldError>올바른 이메일을 입력하세요.</FieldError>
</Field>권장 사항
- ✅
FieldLabel의htmlFor와 입력 요소의id를 반드시 연결 - ✅ 관련 필드는
FieldSet+FieldLegend로 그룹화 - ✅ 에러 상태 시 입력 요소에
aria-invalid속성 추가 - ❌
FieldSeparator를 과도하게 사용하지 않기 (스크린 리더 경험 저하)