FormItem
라벨, 컨트롤, 설명, 에러 메시지를 하나로 묶어주는 폼 필드 래퍼 컴포넌트
개요
FormItem은 Field 컴포넌트 패밀리를 간편하게 사용할 수 있도록 래핑한 컴포넌트입니다. label, description, error 등의 props만으로 접근성 있는 폼 필드를 빠르게 구성할 수 있습니다.
주요 특징
- ✅ 간편한 API: props 기반으로 라벨, 설명, 에러를 한 번에 구성
- ✅ 레이아웃 제어: vertical / horizontal 방향 지원
- ✅ 라벨 정렬: 가로(
labelAlign) / 세로(labelVerticalAlign) 정렬 제어 - ✅ 유효성 검증:
errorprop으로 에러 상태 표시 - ✅ 접근성: Field 컴포넌트 기반의 시맨틱 마크업 자동 적용
사용 예시
기본
Preview
설명 포함
Preview
업무용 이메일을 입력하세요.
필수 입력
Preview
에러 상태
Preview
비밀번호는 8자 이상이어야 합니다.
Horizontal 레이아웃
orientation="horizontal"과 labelWidth를 함께 사용하여 가로 레이아웃을 구성합니다.
Preview
업무용 이메일
Label Align (가로 정렬)
labelAlign prop으로 라벨 텍스트의 가로 정렬을 제어합니다. labelWidth와 함께 사용할 때 효과적입니다.
Preview
Label Vertical Align (세로 정렬)
labelVerticalAlign prop으로 라벨의 세로 정렬을 제어합니다. horizontal 레이아웃에서 description이 있을 때 유용합니다.
Preview
세로 정렬: start
세로 정렬: center
세로 정렬: end
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | - | 라벨 텍스트 |
labelWidth | number | - | 라벨 너비 (px, horizontal 전용) |
labelAlign | "start" | "center" | "end" | - | 라벨 가로 정렬 |
labelVerticalAlign | "start" | "center" | "end" | - | 라벨 세로 정렬 |
description | string | - | 도움말 텍스트 |
orientation | "vertical" | "horizontal" | "responsive" | "vertical" | 레이아웃 방향 |
required | boolean | - | 필수 입력 표시 (*) |
error | string | - | 에러 메시지 (표시 시 description 숨김) |
className | string | - | 추가 CSS 클래스 |
children | React.ReactNode | - | 폼 컨트롤 요소 |
기본 사용법
import { FormItem } from "@vortex/ui-foundation"
<FormItem label="이름" required>
<Input placeholder="홍길동" />
</FormItem>
<FormItem
label="이메일"
orientation="horizontal"
labelWidth={120}
labelAlign="end"
labelVerticalAlign="start"
>
<Input type="email" />
</FormItem>접근성
시맨틱 마크업
- 내부적으로 Field, FieldLabel, FieldDescription, FieldError를 사용하여 시맨틱 마크업 자동 적용
errorprop 사용 시role="alert"이 적용되어 스크린 리더에 즉시 전달
권장 사항
- ✅
labelprop을 항상 지정하여 접근성 확보 - ✅ 에러 상태 시
errorprop으로 명확한 메시지 전달 - ✅ horizontal 레이아웃에서
labelWidth를 일관되게 설정 - ❌
label없이 사용하지 않기 (접근성 저하)
관련 컴포넌트
Last updated on