Field
라벨, 컨트롤, 설명 텍스트를 조합하여 접근성 있는 폼 필드를 구성하는 컴포넌트
개요
Field 컴포넌트 패밀리는 접근성 있는 폼을 구성하기 위한 컴파운드 컴포넌트입니다. 단일 필드부터 복잡한 폼 레이아웃까지 유연하게 조합할 수 있습니다.
주요 특징
- ✅ 컴파운드 컴포넌트: 10개의 서브 컴포넌트로 유연한 폼 구성
- ✅ 레이아웃 제어: vertical, horizontal, responsive 방향 지원
- ✅ 유효성 검증: FieldError를 통한 에러 메시지 표시
- ✅ 접근성:
<fieldset>,role="group"등 시맨틱 마크업 자동 적용 - ✅ 디자인 토큰: 테마 커스터마이징 지원
구조 (Anatomy)
<FieldSet>
<FieldLegend>그룹 제목</FieldLegend>
<FieldDescription>그룹 설명</FieldDescription>
<FieldGroup>
<Field>
<FieldLabel htmlFor="input-id">라벨</FieldLabel>
<FieldContent>{/* Input, Select, Switch 등 */}</FieldContent>
<FieldDescription>도움말 텍스트</FieldDescription>
<FieldError>유효성 검증 메시지</FieldError>
</Field>
<FieldSeparator />
<Field>{/* 다른 필드 */}</Field>
</FieldGroup>
</FieldSet>서브 컴포넌트 목록
| 컴포넌트 | 설명 |
|---|---|
Field | 단일 폼 필드의 루트 컨테이너 (role="group") |
FieldLabel | 필드 라벨 |
FieldTitle | 라벨 대신 사용할 수 있는 제목 (예: Checkbox/Switch와 함께 사용) |
FieldContent | 필드 컨트롤을 감싸는 컨테이너 (horizontal 레이아웃 시 활용) |
FieldDescription | 도움말/설명 텍스트 |
FieldError | 유효성 검증 에러 메시지 |
FieldSeparator | 필드 간 구분선 |
FieldSet | 여러 필드를 그룹화하는 <fieldset> 래퍼 |
FieldLegend | FieldSet의 제목 (<legend>) |
FieldGroup | FieldSet 내부의 필드 배치 컨테이너 |
사용 예시
Input
라벨과 설명이 포함된 기본 입력 필드입니다.
Preview
8자 이상의 영문, 숫자 조합이어야 합니다.
Checkbox
orientation="horizontal"과 FieldContent를 사용하여 체크박스와 라벨, 설명을 나란히 배치합니다.
Preview
서비스 이용약관에 동의합니다.
Switch
Switch 컨트롤과 라벨을 가로로 배치합니다.
Preview
어두운 배경 테마를 활성화합니다.
FieldSet
FieldSet과 FieldLegend로 관련 필드들을 시맨틱하게 그룹화합니다.
Preview
FieldGroup
FieldGroup으로 Field를 쌓아 배치하고, FieldSeparator로 섹션을 구분합니다.
Preview
새로운 소식을 이메일로 받습니다.
브라우저 푸시 알림을 받습니다.
긴급 알림을 SMS로 받습니다.
유효성 검증과 에러
data-invalid을 Field에, aria-invalid을 입력 요소에 추가하여 에러 상태를 표시합니다. FieldError로 에러 메시지를, FieldDescription과 함께 사용할 수 있습니다.
Preview
8자 이상의 영문, 숫자, 특수문자 조합
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를 과도하게 사용하지 않기 (스크린 리더 경험 저하)