Select
먼저 보고, 그다음 계약을 읽습니다
옵션 목록에서 하나를 고르는 커스텀 셀렉트 (Radix Select 기반).
Component intent의도와 경계 읽기
네이티브 <select> 와 달리 옵션 row 의 typography·spacing·아이콘을 디자인 토큰으로 통제한다. 키보드 내비게이션·type-ahead·포털 위치 계산은 Radix Select 가 처리하고, @axe/ui 는 트리거·팝업·focus ring 스타일만 입힌다. Select(Root)·SelectTrigger·SelectValue·SelectContent·SelectItem·SelectGroup·SelectLabel·SelectSeparator 를 조합해 쓴다.
예제
SSOT에 등록된 실제 API 기준 snippet입니다. standalone 배지만 독립 실행 단위이며, fragment는 주변 state·handler 문맥을 생략합니다.
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem,} from "@axe/ui";<Select value={v} onValueChange={setV}> <SelectTrigger> <SelectValue placeholder="국가 선택…" /> </SelectTrigger> <SelectContent> <SelectItem value="kr">한국</SelectItem> <SelectItem value="us">미국</SelectItem> <SelectItem value="jp">일본</SelectItem> </SelectContent></Select>import { Select, SelectTrigger, SelectValue, SelectContent, SelectGroup, SelectLabel, SelectItem, SelectSeparator,} from "@axe/ui";<Select value={v} onValueChange={setV}> <SelectTrigger size="lg"> <SelectValue placeholder="담당자…" /> </SelectTrigger> <SelectContent> <SelectGroup> <SelectLabel>운영</SelectLabel> <SelectItem value="a">강수훈</SelectItem> <SelectItem value="b">한진우</SelectItem> </SelectGroup> <SelectSeparator /> <SelectGroup> <SelectLabel>외부</SelectLabel> <SelectItem value="c">외부 감사인</SelectItem> </SelectGroup> </SelectContent></Select>Props
TSX 소스가 진실입니다. 주요 export 컴포넌트의 public API만 노출합니다.
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
value | string | — | — | 선택된 값 (controlled). Radix Select.Root prop. |
onValueChange | (value: string) => void | — | — | 값이 바뀔 때 콜백 (Root). |
defaultValue | string | — | — | uncontrolled 초기 선택값 (Root). |
disabled | boolean | — | false | 전체 비활성 (Root). |
size | "md" | "lg" | — | "md" | SelectTrigger 높이 토큰. md=36px / lg=44px (Input 과 동일). |
position | "item-aligned" | "popper" | — | "popper" | SelectContent 배치 전략. popper=트리거 아래 앵커. |
sideOffset | number | — | 6 | SelectContent 와 트리거 사이 간격(px). |
placeholder | string | — | — | SelectValue 의 미선택 표시 텍스트 (선택 전 muted 색). |
value (SelectItem) | string | 필수 | — | 각 SelectItem 의 옵션 값 — 선택 시 Root onValueChange 로 전달. |
...rest | 각 Radix Select.* props | — | — | 트리거/콘텐츠/아이템 등 각 파트는 대응 Radix 컴포넌트 props(asChild 포함)를 그대로 전파. |
.axe-* 클래스 계약
React 밖에서도 같은 표면을 그리는 공개 계약입니다. stable은 minor 버전 안에서 이름을 바꾸지 않습니다.
| 클래스 | 안정성 | 용도 |
|---|---|---|
.axe-select__trigger | stable | 트리거 버튼 루트(닫힌 상태 표시). |
.axe-select__trigger--lg | stable | lg 사이즈 변형(44px). |
.axe-select__content | stable | 포털로 뜨는 팝업 패널. |
.axe-select__viewport | internal | 팝업 내부 스크롤 뷰포트(패딩 래퍼) — Radix Viewport. |
.axe-select__label | stable | SelectLabel — 그룹 제목(대문자 트래킹). |
.axe-select__item | stable | 옵션 row. |
.axe-select__indicator | internal | 선택된 항목의 체크 표시 슬롯 — Radix ItemIndicator. |
.axe-select__separator | stable | 그룹 구분선. |
접근성
키보드, ARIA, 구현 노트를 함께 검토합니다.
- Space/Enter/↓ 로 열기
- ↑/↓ 로 항목 이동, Home/End 로 처음/끝
- 글자 입력 시 type-ahead 로 해당 항목 점프
- Enter 로 선택, Esc 로 닫기(트리거로 포커스 복원)
Radix 가 트리거에 aria-haspopup=listbox·aria-expanded 를, 콘텐츠에 role=listbox, 각 아이템에 role=option(선택은 data-state=checked)을 부여. 현재 값은 SelectValue 가 표시.
focus-visible·열림 시 --ring 적용, 미선택 트리거는 data-placeholder 로 muted 색. 부모 .axe-form-field--error 안에서 자동으로 danger 보더/링. prefers-reduced-motion 시 open/close 애니메이션 제거.