Select
드롭다운에서 옵션을 선택하는 폼 컴포넌트
개요
Select는 드롭다운 목록에서 항목을 선택하는 폼 컴포넌트입니다. 그룹화된 옵션 구조를 제공합니다.
주요 특징
- ✅ 그룹화 옵션: group으로 항목 분류
- ✅ 클리어 버튼: 선택 초기화
- ✅ 다양한 크기: xs, sm, md, lg, xl
- ✅ FormItem 통합: 레이블, 설명, 에러 메시지
- ✅ 접근성: WAI-ARIA Select 패턴
- ✅ 디자인 토큰: 테마 커스터마이징 지원
Variants
기본 사용
Preview
그룹화 옵션
Preview
Sizes
Preview
States
Preview
매출
지표를 선택해주세요
사용 예시
필수값 표시
required prop을 사용하면 레이블 좌측에 *(Asterisk)가 표시됩니다.
Preview
읽기 전용 상태
readOnly 상태에서는 선택된 값을 표시하지만 드롭다운이 열리지 않습니다.
Preview
사과
선택된 값이 없습니다
오류 상태
error prop으로 오류 메시지를 표시하며, 오류 상태의 시각적 스타일을 적용합니다.
Preview
필수 선택 항목입니다
레이블 제공
orientation으로 레이블 배치 방향을, description으로 설명 텍스트를 제공합니다.
Preview
항목을 하나 선택해 주세요
값 초기화
clearable prop이 true(기본값)이면 선택된 값을 초기화하는 X 버튼이 표시됩니다. false로 설정하면 초기화 버튼이 숨겨집니다.
Preview
비활성화 옵션
개별 항목에 disabled: true를 설정하면 선택 불가능한 상태로 표시됩니다.
Preview
분석 필터
지표와 기간을 선택합니다. 기간 Select에는 clearable={false}를 설정하여 항상 값이 선택된 상태를 유지합니다.
Preview
프로젝트팀 구현 항목: 아래 기능은 프로젝트 요구사항에 맞춰 직접 구현합니다.
- 미선택 상태 의미 규칙: 조회 조건 등에서 값이 선택되지 않은 상태(Placeholder 노출)는 전체 옵션을 선택한 것으로 해석
- 옵션 개수 제어: 항목의 개수는 일반적으로 10개 이하를 권장
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | SelectItemProps[] | [] | 옵션 항목 배열 |
value | string | - | 선택된 값 (제어) |
defaultValue | string | - | 기본 선택 값 |
onValueChange | (value: string) => void | - | 값 변경 핸들러 |
placeholder | string | - | 플레이스홀더 |
width | string | number | "100%" | 컴포넌트 너비 |
size | "xs" | "sm" | "md" | "lg" | "xl" | - | 컴포넌트 크기 |
disabled | boolean | false | 비활성화 여부 |
readOnly | boolean | false | 읽기 전용 여부 |
clearable | boolean | true | 클리어 가능 여부 |
label | string | - | 필드 레이블 |
labelWidth | string | number | - | 레이블 너비 |
labelAlign | "start" | "center" | "end" | - | 레이블 가로 정렬 |
labelVerticalAlign | "start" | "center" | "end" | - | 레이블 세로 정렬 |
required | boolean | false | 필수 여부 |
orientation | "horizontal" | "vertical" | "horizontal" | 레이블-필드 배치 방향 |
description | string | - | 설명 텍스트 |
error | string | - | 에러 메시지 |
className | string | - | 추가 CSS 클래스 |
SelectItemProps
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | - | 옵션 값 (필수) |
label | string | ReactNode | - | 옵션 레이블 |
group | string | - | 그룹 키 |
disabled | boolean | false | 비활성화 여부 |
separator | boolean | false | 항목 아래 구분선 표시 |
기본 사용법
import { Select } from "@vortex/ui-icignal"
<Select
label="기간"
items={[
{ value: "7d", label: "7일" },
{ value: "30d", label: "30일" },
]}
/>
// 그룹 사용
<Select
label="채널"
items={[
{ group: "온라인", value: "organic", label: "자연 검색" },
{ group: "오프라인", value: "direct", label: "직접 방문" },
]}
/>접근성
ARIA 속성
<Select
label="지표 선택"
items={[
{ value: "revenue", label: "매출" },
{ value: "users", label: "사용자" },
]}
/>권장 사항
- ✅
label을 제공하여 선택 목적 전달 - ✅ 키보드: Space/Enter로 열기, Arrow로 이동, Esc로 닫기
- ✅
aria-expanded,aria-invalid자동 설정 - ❌ placeholder만으로 레이블 대체 지양
관련 컴포넌트
- Combobox: 검색 가능한 드롭다운
- RadioButtonGroup: 라디오 단일 선택
- CheckboxGroup: 체크박스 다중 선택
Last updated on