NativeSelect
브라우저 네이티브 <select> 요소를 스타일링한 선택 컴포넌트
개요
NativeSelect 컴포넌트는 HTML 네이티브 <select> 요소를 기반으로 한 간단한 선택 컴포넌트입니다. 커스텀 드롭다운 UI 없이 브라우저 기본 동작을 그대로 사용하므로 모바일 환경에서 네이티브 피커가 표시되며, 폼 호환성이 뛰어납니다.
주요 특징
- ✅ 네이티브 동작: 브라우저/모바일 네이티브 선택 UI 그대로 사용
- ✅ Sizes: xs, sm, md, lg, xl 5단계 크기
- ✅ 옵션 그룹화: NativeSelectOptGroup으로 옵션 그룹 구성
- ✅ 폼 호환성:
name,required,disabled등 네이티브 폼 속성 지원 - ✅ Invalid 상태:
aria-invalid적용 시 에러 스타일 자동 표시 - ✅ 디자인 토큰: 테마 커스터마이징 지원
구조 (Anatomy)
<NativeSelect>
<NativeSelectOption value="value">옵션</NativeSelectOption>
<NativeSelectOptGroup label="그룹 라벨">
<NativeSelectOption value="value">옵션</NativeSelectOption>
</NativeSelectOptGroup>
</NativeSelect>Sizes
NativeSelect는 5가지 크기를 지원합니다. 기본값은 md입니다.
Preview
사용 예시
기본 사용
Preview
옵션 그룹
NativeSelectOptGroup으로 관련 옵션을 그룹화합니다.
Preview
Disabled / Invalid
비활성 상태와 유효성 검증 에러 상태를 표시합니다.
Preview
API Reference
NativeSelect
네이티브 <select> 요소를 감싸는 루트 컴포넌트입니다. 네이티브 select 속성(value, defaultValue, onChange, name, required, disabled 등)을 그대로 지원합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | 선택 필드 크기 |
disabled | boolean | - | 비활성 상태 |
required | boolean | - | 필수 선택 여부 |
className | string | - | 래퍼 추가 CSS 클래스 |
NativeSelectOption
개별 선택 옵션입니다. 네이티브 <option> 요소를 렌더링합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
value | string | - | 옵션 값 |
disabled | boolean | - | 옵션 비활성화 |
NativeSelectOptGroup
옵션을 그룹화하는 컴포넌트입니다. 네이티브 <optgroup> 요소를 렌더링합니다.
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | - | 그룹 라벨 (필수) |
className | string | - | 추가 CSS 클래스 |
기본 사용법
import {
NativeSelect,
NativeSelectOption,
NativeSelectOptGroup,
} from "@vortex/ui-foundation"
// 기본
<NativeSelect>
<NativeSelectOption value="">선택하세요</NativeSelectOption>
<NativeSelectOption value="option-1">옵션 1</NativeSelectOption>
<NativeSelectOption value="option-2">옵션 2</NativeSelectOption>
</NativeSelect>
// 크기 지정
<NativeSelect size="lg">
<NativeSelectOption value="option-1">옵션 1</NativeSelectOption>
</NativeSelect>접근성
시맨틱 마크업
- 네이티브
<select>요소를 사용하므로role="combobox"가 기본 적용 - 키보드 네비게이션, 포커스 관리, 스크린 리더 지원이 브라우저 네이티브로 제공
aria-invalid="true"설정 시 에러 스타일과 스크린 리더 알림이 함께 동작
권장 사항
- ✅
aria-label또는 Label 컴포넌트와 연결하여 명확한 라벨 제공 - ✅ 모바일 사용성이 중요하거나 간단한 폼에서 사용
- ❌ 커스텀 디자인의 드롭다운이 필요한 경우 Select 컴포넌트 사용