Select
Select는 사용자가 여러 옵션 중에서 하나를 선택할 수 있는 드롭다운 컴포넌트입니다. 폼 입력, 설정 선택, 필터링 등에 사용되며, 키보드 내비게이션과 접근성을 완벽하게 지원합니다.Property
Size
Select의 크기를 설정합니다.
Positioning
Select 드롭다운이 나타날 위치를 설정합니다. 기본값은 'bottom'입니다.
Controlled State
Select의 선택 상태를 외부에서 제어합니다.
States
Select의 다양한 상태(비활성화, 읽기 전용, 오류)를 설정합니다.
Examples
Items Configuration
배열 형태와 객체 형태의 아이템 데이터를 모두 지원합니다.
Grouping Options
관련된 옵션들을 그룹으로 묶어 구조화할 수 있습니다. Group과 GroupLabel, Separator를 사용하여 명확한 구조를 만들 수 있습니다.
Custom Value Display
Select.Value에 함수형 children을 제공하여 선택된 값을 커스터마이징할 수 있습니다.
Props Table
Select.Root
Select 복합 컴포넌트의 루트. 사용자가 팝업의 목록에서 옵션 하나를 고를 수 있습니다. 선택된 값과 열림 상태를 관리하며 size, invalid, placeholder를 파트에 전달합니다. 자체 HTML 요소를 렌더링하지 않습니다.
| Prop | Default | Type |
|---|---|---|
invalid? | false | boolean |
size? | md | smmdlgxl |
defaultOpen? | false | boolean |
defaultValue? | - | Valuenull |
onOpenChange? | - | function |
onValueChange? | - | function |
open? | - | boolean |
value? | - | Valuenull |
children? | - | ReactNode |
placeholder? | - | ReactNode |
actionsRef? | - | React.RefObject<Select.Root.Actions | null> |
autoComplete? | - | string |
disabled? | false | boolean |
form? | - | string |
highlightItemOnHover? | true | boolean |
id? | - | string |
inputRef? | - | React.Ref<HTMLInputElement> |
isItemEqualToValue? | - | function |
items? | - | Record<string, ReactNode>readonly { label: React.ReactNode; value: any; }[]readonly Group<any>[] |
itemToStringLabel? | - | function |
itemToStringValue? | - | function |
modal? | true | boolean |
name? | - | string |
onOpenChangeComplete? | - | function |
readOnly? | false | boolean |
required? | false | boolean |
Select.Trigger
Select.TriggerPrimitive, Select.ValuePrimitive, Select.TriggerIconPrimitive를 선택된 값과 쉐브론 아이콘을 보여 주는 하나의 파트로 합칩니다. <button> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
disabled? | - | boolean |
nativeButton? | true | boolean |
render? | - | ReactElementfunction |
Select.TriggerPrimitive
클릭하면 팝업을 여는 버튼. <button> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
disabled? | - | boolean |
nativeButton? | true | boolean |
render? | <button /> | ReactElementfunction |
Select.ValuePrimitive
트리거 안에 선택된 값을 표시합니다. items의 항목 레이블을 사용하고, 아무것도 선택하지 않았으면 플레이스홀더를 표시합니다. <span> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
children? | - | ReactNodefunction |
render? | - | ReactElementfunction |
Select.PlaceholderPrimitive
아무것도 선택하지 않았을 때 트리거에 표시되는 플레이스홀더 텍스트. <span> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |
Select.TriggerIconPrimitive
팝업을 열 수 있음을 나타내는 트리거 안의 쉐브론 아이콘. <span> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |
Select.Popup
Select.PortalPrimitive, Select.PositionerPrimitive, Select.PopupPrimitive를 하나의 파트로 합칩니다. 포털이나 포지셔너를 대체하려면 portalElement 또는 positionerElement를 사용하세요. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
portalElement? | - | ReactElement<SelectPortalPrimitive.Props> |
positionerElement? | - | ReactElement<SelectPositionerPrimitive.Props> |
style? | - | React.CSSPropertiesfunction |
finalFocus? | - | booleanReact.RefObject<HTMLElement | null>function |
render? | - | ReactElementfunction |
Select.PortalPrimitive
팝업을 일반 DOM 계층 밖에 렌더링하는 포털 컨테이너. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
container? | - | HTMLElementShadowRootReact.RefObject<HTMLElement | ShadowRoot | null>null |
render? | - | ReactElementfunction |
Select.PositionerPrimitive
팝업을 트리거 기준으로 배치하고 뷰포트 안에 유지합니다. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
align? | start | centerendstart |
alignItemWithTrigger? | false | boolean |
alignOffset? | 0 | numberfunction |
anchor? | - | ElementVirtualElementReact.RefObject<Element | null>functionnull |
arrowPadding? | 5 | number |
collisionAvoidance? | - | CollisionAvoidance |
collisionBoundary? | clipping-ancestors | Boundary |
collisionPadding? | 5 | Padding |
disableAnchorTracking? | false | boolean |
positionMethod? | absolute | fixedabsolute |
side? | bottom | bottomleftrighttopinline-endinline-start |
sideOffset? | 4 | numberfunction |
sticky? | false | boolean |
render? | - | ReactElementfunction |
Select.PopupPrimitive
옵션을 담는 팝업 패널. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
finalFocus? | - | booleanReact.RefObject<HTMLElement | null>function |
render? | - | ReactElementfunction |
Select.Item
Select.ItemPrimitive, Select.ItemIndicatorPrimitive를 하나의 파트로 합치며, 체크 표시는 레이블 뒤에 놓입니다. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
value? | null | any |
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
disabled? | false | boolean |
label? | - | string |
nativeButton? | false | boolean |
render? | - | ReactElementfunction |
Select.ItemPrimitive
팝업에서 사용자가 선택할 수 있는 옵션. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
value? | null | any |
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
disabled? | false | boolean |
label? | - | string |
nativeButton? | false | boolean |
render? | - | ReactElementfunction |
Select.ItemIndicatorPrimitive
항목이 선택된 동안 표시되는 체크 표시. <span> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
keepMounted? | - | boolean |
render? | - | ReactElementfunction |
Select.Group
관련 옵션을 Select.GroupLabel 아래에 묶습니다. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |
Select.GroupLabel
보조기술이 읽어 주는 옵션 그룹의 레이블. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |
Select.Separator
옵션 그룹을 시각적으로 구분하는 선. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
orientation? | horizontal | horizontalvertical |
render? | - | ReactElementfunction |