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
Root of the Select compound component, which lets the user pick one option from a list in a popup. Manages the selected value and open state, and passes size, invalid, and placeholder to its parts. Doesn't render its own HTML element.
| 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
Combines Select.TriggerPrimitive, Select.ValuePrimitive, and Select.TriggerIconPrimitive into a single part that shows the selected value and a chevron icon. Renders a <button> element.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
disabled? | - | boolean |
nativeButton? | true | boolean |
render? | - | ReactElementfunction |
Select.TriggerPrimitive
Button that opens the popup when clicked. Renders a <button> element.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
disabled? | - | boolean |
nativeButton? | true | boolean |
render? | <button /> | ReactElementfunction |
Select.ValuePrimitive
Shows the selected value inside the trigger, using the item's label from items, or the placeholder when nothing is selected. Renders a <span> element.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
children? | - | ReactNodefunction |
render? | - | ReactElementfunction |
Select.PlaceholderPrimitive
Placeholder text shown in the trigger when nothing is selected. Renders a <span> element.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |
Select.TriggerIconPrimitive
Chevron icon in the trigger that shows the popup can be opened. Renders a <span> element.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |
Select.Popup
Combines Select.PortalPrimitive, Select.PositionerPrimitive, and Select.PopupPrimitive into a single part. Use portalElement or positionerElement to replace the portal or positioner. Renders a <div> element.
| 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
Portal container that renders the popup outside the normal DOM hierarchy. Renders a <div> element.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
container? | - | HTMLElementShadowRootReact.RefObject<HTMLElement | ShadowRoot | null>null |
render? | - | ReactElementfunction |
Select.PositionerPrimitive
Positions the popup against its trigger and keeps it inside the viewport. Renders a <div> element.
| 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
The popup panel that holds the options. Renders a <div> element.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
finalFocus? | - | booleanReact.RefObject<HTMLElement | null>function |
render? | - | ReactElementfunction |
Select.Item
Combines Select.ItemPrimitive and Select.ItemIndicatorPrimitive into a single part, with the check mark after the label. Renders a <div> element.
| 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
Option in the popup that the user can select. Renders a <div> element.
| 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
Check mark shown while the item is selected. Renders a <span> element.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
keepMounted? | - | boolean |
render? | - | ReactElementfunction |
Select.Group
Groups related options under a Select.GroupLabel. Renders a <div> element.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |
Select.GroupLabel
Label for a group of options, announced to assistive technologies. Renders a <div> element.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |
Select.Separator
Line that visually separates groups of options. Renders a <div> element.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
orientation? | horizontal | horizontalvertical |
render? | - | ReactElementfunction |