FormItem
라벨, 컨트롤, 설명, 에러 메시지를 하나로 묶어주는 폼 필드 래퍼 컴포넌트
개요
FormItem은 Field 컴포넌트 패밀리를 간편하게 사용할 수 있도록 래핑한 컴포넌트입니다. label, description, error 등의 props만으로 접근성 있는 폼 필드를 빠르게 구성할 수 있습니다.
주요 특징
- ✅ 간편한 API: props 기반으로 라벨, 설명, 에러를 한 번에 구성
- ✅ 레이아웃 제어: vertical / horizontal 방향 지원
- ✅ 라벨 정렬: 가로(
labelAlign) / 세로(labelVerticalAlign) 정렬 제어 - ✅ 필수 마커 제어:
*마커의 위치(left/right)와 오프셋(x, y) 조정 - ✅ 유효성 검증:
errorprop으로 에러 상태 표시 - ✅ 접근성: Field 컴포넌트 기반의 시맨틱 마크업 자동 적용
사용 예시
기본
Preview
설명 포함
Preview
업무용 이메일을 입력하세요.
필수 입력
Preview
필수 마커 위치 제어
requiredPosition으로 * 마커를 라벨 왼쪽/오른쪽에 배치하고, requiredOffsetX / requiredOffsetY로 미세 조정합니다.
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
Form (Context Provider)
Form으로 감싸면 labelWidth, orientation, required 등을 한 번에 지정할 수 있습니다. 개별 FormItem에서 같은 prop을 지정하면 오버라이드됩니다.
Preview
API Reference
FormItem 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 | - | 필수 입력 표시 (*) |
requiredPosition | "left" | "right" | "left" | * 마커 위치 (라벨 기준) |
requiredOffsetX | number | 0 | * 마커 수평 오프셋 (px) |
requiredOffsetY | number | 0 | * 마커 수직 오프셋 (px) |
error | string | - | 에러 메시지 (표시 시 description 숨김) |
className | string | - | 추가 CSS 클래스 |
children | React.ReactNode | - | 폼 컨트롤 요소 |
Form Props
Form은 <form> 엘리먼트의 모든 HTML 속성을 지원하며, 추가로 다음 props를 받습니다.
이 값들은 하위 FormItem에 Context로 전달되어 기본값으로 사용됩니다.
| Prop | Type | Default | Description |
|---|---|---|---|
labelWidth | number | - | 라벨 너비 (px) |
labelAlign | "start" | "center" | "end" | - | 라벨 가로 정렬 |
labelVerticalAlign | "start" | "center" | "end" | - | 라벨 세로 정렬 |
orientation | "vertical" | "horizontal" | "responsive" | - | 레이아웃 방향 |
required | boolean | - | 전체 필수 입력 표시 |
requiredPosition | "left" | "right" | - | * 마커 위치 |
requiredOffsetX | number | - | * 마커 수평 오프셋 (px) |
requiredOffsetY | number | - | * 마커 수직 오프셋 (px) |
className | string | - | 추가 CSS 클래스 |
children | React.ReactNode | - | FormItem 등 하위 요소 |
기본 사용법
import { Form, FormItem } from "@vortex/ui-foundation"
{/* FormItem 단독 사용 */}
<FormItem label="이름" required>
<Input placeholder="홍길동" />
</FormItem>
{/* Form으로 공통 설정 */}
<Form orientation="horizontal" labelWidth={120} labelAlign="end" required>
<FormItem label="이름">
<Input placeholder="홍길동" />
</FormItem>
<FormItem label="이메일">
<Input type="email" />
</FormItem>
</Form>접근성
시맨틱 마크업
- 내부적으로 Field, FieldLabel, FieldDescription, FieldError를 사용하여 시맨틱 마크업 자동 적용
errorprop 사용 시role="alert"이 적용되어 스크린 리더에 즉시 전달
권장 사항
- ✅
labelprop을 항상 지정하여 접근성 확보 - ✅ 에러 상태 시
errorprop으로 명확한 메시지 전달 - ✅ horizontal 레이아웃에서
labelWidth를 일관되게 설정 - ❌
label없이 사용하지 않기 (접근성 저하)
관련 컴포넌트
Last updated on