Select
옵션 목록에서 값을 선택하는 Select 컴포넌트입니다. 네이티브 <select class="input">와 커스텀 드롭다운 트리거 btn_select · btn_select-text 두 가지 유형을 제공합니다.
유형
네이티브 select는 브라우저 기본 목록을 사용합니다. 커스텀 트리거는 Dropdown·Popover와 조합해 검색·다중 선택 등 확장 UI에 적합합니다.
폼 필드·간단한 선택에 권장합니다.
btn_select는 input과 유사한 박스형, btn_select-text는 정렬·필터용 텍스트형 트리거입니다.
기본
레이블과 힌트 텍스트가 포함된 폼 필드입니다.
계정에 부여할 권한을 선택해 주세요.
단독 사용
form_field 없이 select만 사용할 수 있습니다. 인라인 필터·툴바 등에 적합합니다.
크기
input_sm · input(기본) · input_lg로 padding·font-size를 조절합니다. 커스텀 트리거는 btn_sm · btn · btn_lg를 사용합니다.
너비
기본은 부모 100%, input_fit · form_field_fit으로 --input-max-width(320px)까지 제한합니다. btn_select는 btn_block으로 전체 너비를 사용합니다.
플레이스홀더
빈 value의 option과 required · disabled · selected · hidden으로 미선택 상태를 표현합니다. 커스텀 트리거는 btn_select-placeholder 클래스를 사용합니다.
required와 함께 사용하면 미선택 시 placeholder 색상이 적용됩니다.
옵션 그룹
optgroup으로 관련 옵션을 묶어 표시합니다. label 속성으로 그룹 제목을 지정합니다.
다중 선택
multiple 속성으로 여러 옵션을 동시에 선택합니다. Ctrl(Windows) · Cmd(Mac) 키로 복수 선택이 가능합니다.
복수 선택 시 listSize로 표시 행 수를 지정합니다. (네이티브 size 속성)
상태
disabled · is-error · is-success로 선택 상태를 표현합니다. 커스텀 트리거는 is-open · is-error · aria-expanded를 함께 사용합니다.
disabled 속성으로 선택을 막습니다.
필수 항목입니다. 옵션을 선택해 주세요.
커스텀 트리거
btn_select · btn_select-text는 Button 컴포넌트 스타일을 공유합니다. aria-haspopup="listbox" · aria-expanded · btn_select-caret을 지정하고, Dropdown·Popover 패널과 조합해 사용합니다.
상세 변형은 Button — 셀렉트 박스형 섹션을 참고하세요.
조합 예시
유효성 검사와 함께 네이티브 select를 사용한 회원가입 폼입니다.
API · Props
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
ref | React.Ref<HTMLSelectElement | HTMLButtonElement> | — | native select 또는 custom 버튼 트리거 DOM 참조 |
value | string | number | string[] | — | 제어 컴포넌트 값 (Vue model-value 대응) |
defaultValue | string | number | string[] | — | 비제어 초기 값 |
size | 'sm' | 'md' | 'lg' | md | input_sm · btn_sm 등 크기 |
listSize | number | — | 네이티브 size — multiple 표시 행 수 |
multiple | boolean | false | 네이티브 다중 선택 |
placeholder | string | — | 미선택 placeholder |
disabled | boolean | false | 비활성 |
error | boolean | false | 오류 상태 (is-error) |
open | boolean | false | custom 트리거 열림 (is-open) |
block | boolean | false | 부모 너비 100% |
custom | boolean | false | button 트리거 + listbox 패턴 |
selectText | boolean | false | 텍스트형 트리거 (btn_select-text) |
className | string | — | select/input 또는 custom 트리거에 추가 클래스 |
onChange | (event) => void | — | 값 변경 콜백 (Vue update:modelValue 대응) |
...rest | React.SelectHTMLAttributes<HTMLSelectElement> | — | name · required · autoComplete 등 네이티브 속성 전달 |
ripple | boolean | — | 클릭 파장(ripple). custom 트리거일 때만 적용 · true 활성 · false 비활성 |
API · Children
| Children | 설명 |
|---|---|
default | option 요소 또는 custom 트리거 라벨 |
API · Events
| 이벤트 | 설명 |
|---|---|
onChange | 선택 값 변경 시 (Vue update:modelValue 대응) |
onClick | custom 버튼 트리거 클릭 시 |
클래스 · 속성
React 컴포넌트가 렌더하는 OOCSS 클래스입니다. HTML 마크업으로 직접 작성할 때 동일하게 조합합니다.
| 클래스 | 설명 |
|---|---|
input (native) | 네이티브 select 스타일 |
btn_select · btn_select-text · btn_select-caret | custom 트리거 |
btn_select-placeholder · is-open | 트리거 상태 |
select_dropdown · select_option | 드롭다운 패널 (HTML 마크업) |
is-error · is-disabled | 상태 |
data-ripple | 클릭 파장 활성. data-ripple="surface"는 절대 위치 보조 버튼용 |
data-ripple="false" | 해당 요소 ripple 비활성 |
data-no-ripple | 하위 전체 ripple 비활성 |
디자인 토큰
| 토큰 | 기본값 | 설명 |
|---|---|---|
--select-padding-right · --select-padding-right-sm · --select-padding-right-lg | 2.25rem · 2rem · 2.5rem | 캐럿 공간(우측 패딩) |
--select-caret-offset · --select-caret-offset-sm · --select-caret-offset-lg | 0.65rem · 0.5rem · 0.85rem | 캐럿 위치 |
--select-caret-size · --select-caret-size-sm · --select-caret-size-lg | 1em · 0.875em · 1.125em | 캐럿 아이콘 크기 |