Select

Radix UI 기반의 접근성을 고려한 선택 목록 컴포넌트입니다. 키보드 네비게이션과 스크린 리더를 완전히 지원합니다.

개요

Select는 여러 옵션 중 하나를 선택할 수 있는 컴포넌트입니다. Radix UI를 기반으로 구축되어 완전한 접근성과 키보드 네비게이션을 제공합니다.

설치

사용법

Select 컴포넌트를 import하여 사용합니다. options prop으로 선택 가능한 항목들을 전달하고, value와 onChange로 상태를 관리합니다.

예제

FormField와 함께 사용 (권장)

FormField를 사용하면 label, error, helper text를 일관되게 관리하고 접근성 속성이 자동으로 연결됩니다. 폼에서 Select를 사용할 때 권장하는 방법입니다.

가장 좋아하는 과일을 하나 선택해주세요.

에러 상태

FormField의 status prop과 FormError를 사용하여 필수 선택 항목이 선택되지 않았거나 유효하지 않을 때 에러 상태를 표시할 수 있습니다. 에러 메시지가 자동으로 aria-describedby에 연결되어 스크린 리더가 읽을 수 있습니다.

크기

size prop으로 Select의 높이를 조절할 수 있습니다. 기본값은 lg(56px)입니다.

비활성화

disabled prop으로 특정 조건이 충족되지 않아 선택을 받을 수 없을 때 비활성화 상태를 표시할 수 있습니다.

사용 가이드

Select를 효과적으로 사용하기 위한 가이드입니다:

Select를 사용하기 적합한 경우:

  • 옵션이 5개 이상인 경우
  • 국가, 도시 등 많은 선택지가 있는 경우
  • 카테고리, 분류를 선택할 때
  • 정렬 옵션 선택 (최신순, 인기순 등)

Select를 사용하지 말아야 하는 경우:

  • 선택지가 3개 이하인 경우 (Radio Button 사용)
  • 모든 옵션을 한눈에 비교해야 하는 경우 (Radio Button 사용)
  • 텍스트 입력이 필요한 경우 (Input with Autocomplete 사용)

주의사항:

  • 논리적 순서: 알파벳순, 가나다순 등 예측 가능한 순서로 정렬하세요.
  • 명확한 레이블: "선택하세요"가 아닌 "배송 국가를 선택하세요"처럼 구체적으로 작성하세요.
  • 레이블 필수: label 요소로 명확한 레이블을 제공하세요.

접근성

Select는 WCAG 2.1 / KWCAG 2.2 Level AA 기준을 준수합니다.

  • Radix UI 기반: @radix-ui/react-select를 사용하여 완전한 접근성과 ARIA 속성을 자동으로 제공합니다.
  • FormField 통합: FormField와 함께 사용하면 aria-invalid, aria-required, aria-describedby 속성이 자동으로 연결되어 에러 메시지와 도움말을 스크린 리더가 읽을 수 있습니다.
  • 키보드 네비게이션: Arrow Up/Down (옵션 이동), Enter (선택), Escape (닫기), Space (열기) 키로 완전한 키보드 탐색을 지원합니다.
  • 스크린 리더: role="combobox" 및 aria-expanded로 드롭다운 상태를 전달하며, 선택된 옵션을 명확히 알립니다.
  • Focus Management: 드롭다운 열기/닫기 시 자동 포커스 관리 및 focus trap을 제공합니다.
  • Type-ahead: 키보드 입력으로 옵션을 빠르게 검색할 수 있습니다.
  • 명도 대비 4.5:1 이상을 준수하여 시각적 접근성을 보장합니다.