Select
옵션 목록에서 하나를 선택하는 드롭다운 컴포넌트
개요
Select 컴포넌트는 base-ui의 Select Primitive를 기반으로 구축된 드롭다운 선택 컴포넌트입니다. SelectValue의 items prop을 통해 선택된 값의 라벨을 표시하고, SelectTrigger의 size prop으로 크기를 제어합니다.
주요 특징
- ✅ 컴파운드 컴포넌트: Select, SelectTrigger, SelectValue, SelectContent, SelectItem 등 유연한 구성
- ✅ Sizes: SelectTrigger에 xs, sm, md, lg, xl 5단계 크기
- ✅ 그룹화: SelectGroup + SelectLabel로 옵션 그룹화
- ✅ 접근성: 키보드 네비게이션, ARIA 속성 자동 적용
- ✅ 디자인 토큰: 테마 커스터마이징 지원
구조 (Anatomy)
<Select>
<SelectTrigger>
<SelectValue placeholder="선택하세요" items={items} />
</SelectTrigger>
<SelectContent>
<SelectGroup>
<SelectLabel>그룹 라벨</SelectLabel>
<SelectItem value="value">옵션</SelectItem>
</SelectGroup>
</SelectContent>
</Select>Sizes
SelectTrigger에 5가지 크기를 지원합니다. 기본값은 md입니다.
Preview
사용 예시
기본 사용
Preview
items prop으로 라벨 매핑
SelectValue의 items prop에 { value, label } 배열을 전달하면 선택된 값의 라벨을 자동으로 표시합니다.
Preview
그룹화
SelectGroup과 SelectLabel로 옵션을 그룹화합니다.
Preview
비활성 상태
Select 전체 또는 개별 SelectItem을 비활성화할 수 있습니다.
Preview
기본값 설정 (defaultValue)
defaultValue prop을 사용하면 초기 선택값을 지정할 수 있습니다. 비제어 모드에서 사용되며, SelectItem의 value와 일치하는 값을 전달합니다.
Preview
Label과 함께 사용
Preview
오류 상태
aria-invalid 속성을 통해 오류 상태를 시각적으로 표시합니다.
Preview
구분선(Separator)으로 옵션 분리
SelectSeparator를 사용하여 옵션 그룹 사이에 시각적 구분선을 표시합니다.
Preview
API Reference
Select
드롭다운 선택의 루트 컴포넌트입니다. base-ui Select.Root를 래핑합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
defaultValue | string | - | 초기 선택값 |
value | string | - | 제어 모드 선택값 |
onValueChange | (value: string) => void | - | 값 변경 콜백 |
disabled | boolean | - | 비활성 상태 |
required | boolean | - | 필수 선택 여부 |
SelectTrigger
드롭다운을 여는 트리거 버튼입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | 트리거 크기 |
className | string | - | 추가 CSS 클래스 |
SelectValue
선택된 값을 표시하는 컴포넌트입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
placeholder | React.ReactNode | - | 미선택 시 표시 텍스트 |
items | Array<{ value: string; label: React.ReactNode }> | - | 값-라벨 매핑 배열 |
className | string | - | 추가 CSS 클래스 |
SelectContent
드롭다운 팝업 컨테이너입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
side | "top" | "bottom" | "left" | "right" | "bottom" | 팝업 위치 |
sideOffset | number | 4 | 트리거와의 간격 |
align | "start" | "center" | "end" | "center" | 정렬 방향 |
alignOffset | number | 0 | 정렬 오프셋 |
className | string | - | 추가 CSS 클래스 |
SelectItem
개별 선택 옵션입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | - | 옵션 값 (필수) |
disabled | boolean | - | 비활성 상태 |
className | string | - | 추가 CSS 클래스 |
SelectGroup
옵션을 그룹화하는 컨테이너입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
SelectLabel
SelectGroup의 라벨입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
SelectSeparator
옵션 그룹 사이의 구분선입니다.
| Prop | Type | Default | Description |
|---|---|---|---|
className | string | - | 추가 CSS 클래스 |
기본 사용법
import {
Select,
SelectTrigger,
SelectValue,
SelectContent,
SelectItem,
SelectGroup,
SelectLabel,
SelectSeparator,
} from "@vortex/ui-foundation"
// 기본
<Select>
<SelectTrigger className="w-[200px]">
<SelectValue placeholder="선택하세요" items={items} />
</SelectTrigger>
<SelectContent>
<SelectItem value="option-1">옵션 1</SelectItem>
<SelectItem value="option-2">옵션 2</SelectItem>
</SelectContent>
</Select>접근성
ARIA 속성
- base-ui가
role="combobox",aria-expanded,aria-controls를 자동 설정 - 선택된 아이템에 체크 아이콘 표시기(SelectItemIndicator) 자동 렌더링
키보드 네비게이션
- Space / Enter: 드롭다운 열기/닫기
- Arrow Up / Down: 옵션 탐색
- Home / End: 처음/마지막 옵션으로 이동
- Esc: 드롭다운 닫기
권장 사항
- ✅ Label과 함께 사용하여 접근성 보장 (
htmlFor와id연결) - ✅ 명확한 placeholder 텍스트 제공
- ✅ 4개 이상의 옵션일 때 Select 사용
- ❌ 2-3개 옵션은 RadioGroup 사용 권장
관련 컴포넌트
Last updated on