FormField

폼 필드를 구성하는 컴포넌트 그룹입니다. 레이블, 입력 필드, 에러 메시지, 도움말을 자동으로 연결하여 완전한 접근성을 제공합니다.

개요

설치

사용법

FormField는 4개의 컴포넌트로 구성됩니다:

  1. FormField - 컨테이너, Context 제공
  2. FormLabel - 레이블, 필수 표시 자동
  3. 입력 컴포넌트 - Input, Textarea, Select, Checkbox, Radio, Switch
  4. FormError 또는 FormHelperText - 에러 메시지 또는 도움말

지원 컴포넌트

FormField는 다양한 폼 입력 컴포넌트와 함께 사용할 수 있습니다. 각 컴포넌트는 useFormField 훅을 통해 자동으로 FormField와 연결됩니다.

Textarea

최소 10자 이상 작성해주세요

Select

적절한 카테고리를 선택해주세요

Checkbox / CheckboxGroup

서비스 이용을 위해 필수 동의가 필요합니다
최소 1개 이상 선택해주세요

Radio / RadioGroup

서비스 이용 통계에 활용됩니다

Switch

새로운 소식을 알림으로 받습니다

예제

기본 사용

읽기 전용 - 수정할 수 없습니다
입력할 수 없습니다

필수 필드 (Required)

도움말 (Helper Text)

영문, 숫자, 특수문자 포함 8자 이상

상태

FormField는 에러, 성공, 정보 상태를 지원하며, 자동으로 하위 Input에 상태가 전달됩니다.

사용 가능한 이메일입니다
회사 이메일을 사용하세요

아이콘 버튼

FormField의 clearable prop을 사용하면 입력값이 있을 때 X 버튼이 자동으로 나타납니다. 비밀번호 필드는 추가로 Eye/EyeOff 토글 버튼이 제공됩니다. 모든 아이콘 버튼은 마우스 오버 시 primary-60 색상으로 변경되어 상호작용을 명확히 표시합니다.

4-20자의 영문자와 숫자만 사용 가능합니다
영문, 숫자, 특수문자 포함 8자 이상

접근성

FormField는 WCAG 2.1 AA 기준을 준수하며 자동으로 접근성 속성을 연결합니다.

자동 연결되는 속성

  • htmlFor - FormLabel이 자동으로 Input의 id와 연결
  • aria-required - required prop이 Input에 자동 전달
  • aria-invalid - error prop이 true일 때 Input에 자동 설정
  • aria-describedby - FormError와 FormHelperText의 id가 Input에 자동 연결
  • role="alert" 및 aria-live="polite" - FormError에 자동 설정

스크린 리더 지원

FormField를 사용하면 스크린 리더 사용자에게 다음 정보가 자동으로 전달됩니다:

  1. 레이블 텍스트와 필수 여부 (* 표시)
  2. 입력 필드의 타입과 현재 값
  3. 도움말 텍스트 (있는 경우)
  4. 에러 메시지 (에러 상태일 때)

모범 사례

  • 항상 FormLabel을 제공하여 필드의 목적을 명확하게 표시하세요
  • 필수 필드는 required prop을 사용하여 표시하세요
  • 에러 발생 시 FormError로 명확한 해결 방법을 제공하세요
  • 복잡한 입력 규칙은 FormHelperText로 사전에 안내하세요
  • 각 FormField에 고유한 id를 제공하세요 (자동 생성도 가능)

작동 원리

FormField는 React Context API를 사용하여 자식 컴포넌트들 간에 상태를 공유합니다: