Form

폼 전체의 레이아웃과 라벨 설정을 일괄 적용하는 폼 컨테이너 컴포넌트

개요

Form 컴포넌트는 내부의 FormItem들에게 orientation, labelWidth, required 등의 설정을 Context로 일괄 전달하는 <form> 래퍼입니다. 각 FormItem에 동일한 props를 반복해서 지정할 필요 없이 폼 단위로 레이아웃을 통일할 수 있습니다.

주요 특징

• ✅ 일괄 레이아웃: Form 레벨의 설정이 모든 하위 FormItem에 Context로 전파
• ✅ 가로 레이아웃: orientation="horizontal"과 labelWidth로 라벨 고정 폭 지정
• ✅ 라벨 정렬: labelAlign / labelVerticalAlign으로 라벨 가로·세로 정렬 제어
• ✅ 필수 마커 전역 제어: required, requiredPosition, 오프셋을 폼 단위로 지정
• ✅ 개별 오버라이드: FormItem의 props가 Form의 Context 값보다 우선 적용
• ✅ react-hook-form 통합: @vortex/ui-foundation에서 react-hook-form API를 함께 re-export

사용 예시

기본 (세로 레이아웃)

기본적으로 FormItem은 세로(vertical) 방향으로 배치됩니다.

<Form>
  <FormItem label="사용자 이름">
    <Input placeholder="johndoe" />
  </FormItem>
  <FormItem label="이메일" description="업무용 이메일을 입력하세요.">
    <Input type="email" placeholder="user@example.com" />
  </FormItem>
  <Button type="submit" className="self-start">
    제출
  </Button>
</Form>

가로 레이아웃 + 라벨 고정 폭

orientation="horizontal"과 labelWidth를 Form에 한 번만 지정하면 모든 FormItem에 적용됩니다.

<Form orientation="horizontal" labelWidth={100}>
  <FormItem label="이름">
    <Input placeholder="홍길동" />
  </FormItem>
  <FormItem label="이메일">
    <Input type="email" placeholder="user@example.com" />
  </FormItem>
  <FormItem label="연락처">
    <Input placeholder="010-0000-0000" />
  </FormItem>
</Form>

필수 마커 전역 적용

required와 requiredPosition을 Form 레벨에서 지정하면 모든 FormItem의 라벨에 * 마커가 표시됩니다.

<Form
  orientation="horizontal"
  labelWidth={100}
  labelAlign="end"
  required
  requiredPosition="right"
>
  <FormItem label="이름">
    <Input placeholder="홍길동" />
  </FormItem>
  <FormItem label="이메일">
    <Input type="email" placeholder="user@example.com" />
  </FormItem>
  {/* 개별 FormItem에서 오버라이드 가능 */}
  <FormItem label="비고" required={false}>
    <Input placeholder="선택 입력" />
  </FormItem>
</Form>

API Reference

Props

FormProps는 React.FormHTMLAttributes<HTMLFormElement>를 상속합니다.

기본 사용법

import { Form, FormItem, Input, Button } from "@vortex/ui-foundation"
 
;<Form onSubmit={handleSubmit}>
  <FormItem label="이름" required>
    <Input />
  </FormItem>
  <Button type="submit">저장</Button>
</Form>

react-hook-form과 함께 사용하는 경우 패키지에서 관련 API를 그대로 import할 수 있습니다.

import { Form, useForm } from "@vortex/ui-foundation"
 
function MyForm() {
  const { register, handleSubmit } = useForm()
  return (
    <Form onSubmit={handleSubmit(onSubmit)}>
      {/* ... */}
    </Form>
  )
}

접근성

• 네이티브 <form> 요소를 렌더링하여 기본 폼 시맨틱과 제출 동작을 유지합니다.
• 하위 FormItem은 Field 컴포넌트 기반으로 라벨과 컨트롤이 자동 연결됩니다.
• ✅ onSubmit에서 기본 제출 동작을 제어하고 키보드 Enter 제출을 지원하세요.
• ✅ 에러 메시지는 FormItem의 error prop을 사용해 스크린 리더에 노출되도록 하세요.

관련 컴포넌트

• FormItem: 라벨, 설명, 에러를 묶어주는 폼 필드 래퍼
• Field: FormItem의 기반이 되는 저수준 필드 컴포넌트
• Input: 폼에서 사용하는 기본 입력 컴포넌트