Input

다양한 스타일과 크기를 지원하는 입력 필드 컴포넌트입니다. 타입별 최적화 기능(비밀번호 토글, 숫자 키보드 등)과 FormField 자동 통합을 제공하며, KRDS 표준을 준수합니다.

개요

설치

사용법

예제

Size

Variant

Status (상태)

입력 필드의 상태를 시각적으로 표시합니다. 에러, 성공, 정보 상태를 지원하며, 각 상태에 맞는 border 색상이 적용됩니다.

ReadOnly (읽기 전용)

Clearable (지우기 버튼)

입력값이 있을 때 X 버튼을 표시하여 빠르게 지울 수 있습니다. 비밀번호 입력에서는 보안상 표시되지 않습니다.

아이콘 (Addon)

Input Types

Input 컴포넌트는 다양한 입력 타입을 지원하며, 각 타입에 최적화된 기능을 제공합니다.

  • Password: 자동으로 비밀번호 표시/숨김 토글 버튼 제공 (lucide-react Eye/EyeOff 아이콘)
  • Number: 모바일에서 숫자 키보드 자동 활성화 (inputMode="numeric")
  • Text/Email/Tel/URL: 표준 브라우저 동작 지원
  • ReadOnly: 값을 볼 수는 있지만 수정할 수 없는 상태 (readOnly prop)
  • Clearable: 입력값이 있을 때 X 버튼으로 빠르게 지우기 (clearable prop, password 제외)

FormField와 함께 사용 (권장)

FormField 컴포넌트와 함께 사용하면 레이블, 에러 메시지, 도움말이 자동으로 연결됩니다.

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

접근성

Input 컴포넌트는 WCAG 2.1 AA 기준을 준수하며 완전한 접근성을 제공합니다.

키보드 지원

  • Tab - 입력 필드로 포커스 이동
  • Enter - 폼 제출 (form 내부인 경우)
  • Escape - 입력 취소 (브라우저 기본 동작)

스크린 리더 지원

  • aria-invalid - 에러 상태를 자동으로 전달 (status="error" 또는 error prop 사용 시)
  • aria-required - 필수 입력 표시 지원
  • aria-describedby - 에러 메시지 및 도움말 연결 지원
  • aria-label - 아이콘 버튼에 자동 적용 (비밀번호 토글: "비밀번호 보기/숨기기", 지우기 버튼: "입력 지우기")
  • 모든 HTML input 속성 지원 (id, name, disabled, readOnly 등)

폼 통합 예제

권장 방법: FormField 컴포넌트를 사용하면 접근성 속성이 자동으로 연결됩니다.

모범 사례

  • 권장: FormField 컴포넌트와 함께 사용하여 접근성 속성을 자동으로 연결하세요
  • 항상 레이블을 제공하여 입력 필드의 목적을 명확하게 표시하세요 (FormLabel 또는 <label>)
  • 필수 입력 필드는 시각적(*)과 프로그래밍적(required prop) 표시를 모두 제공하세요
  • 에러 메시지는 FormError를 사용하거나 aria-describedby로 연결하세요
  • placeholder는 힌트로만 사용하고, 레이블을 대체하지 마세요
  • 상태별로 적절한 prop을 사용하세요:
    • status="error/success/info" - 입력 상태 시각화
    • disabled - 입력 불가능한 상태 (시각적 + 기능적)
    • readOnly - 읽기 전용 (수정 불가, 값 보기만 가능)
  • 적절한 type 속성을 사용하세요:
    • password - 자동 visibility toggle 제공 (lucide-react 아이콘)
    • number - 모바일 숫자 키보드 활성화 (inputMode="numeric")
    • email/tel/url - 브라우저 자동완성 활용
  • clearable prop으로 사용자 경험 향상 (검색 필드, 필터 등)