MultiSelect
MultiSelect는 사용자가 여러 옵션 중에서 다중 선택할 수 있는 드롭다운 컴포넌트입니다. 선택된 값들은 배지 형태로 표시되며, 태그 선택, 필터링, 카테고리 선택 등에 사용됩니다.Property
Size
MultiSelect의 크기를 설정합니다.
Controlled State
MultiSelect의 선택 상태를 제어합니다.
States
MultiSelect의 다양한 상태를 설정합니다.
Examples
Items Configuration
다양한 형태의 아이템 데이터를 사용합니다.
Grouping Options
옵션을 그룹으로 묶어 구조화합니다.
Custom Value Display
MultiSelect.Value에 함수형 children을 제공하여 선택된 값들의 표시 방법을 커스터마이징할 수 있습니다. 기본적으로는 배지 형태로 표시되지만, 문자열이나 커스텀 컴포넌트로 변경할 수 있습니다.
Props Table
MultiSelect.Root
Root of the MultiSelect compound component, which lets the user pick several options from a list in a popup. Manages the selected values 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? | - | readonly Value[]null |
onOpenChange? | - | function |
onValueChange? | - | function |
open? | - | boolean |
value? | - | readonly Value[]null |
children? | - | ReactNode |
placeholder? | - | ReactNode |
actionsRef? | - | React.RefObject<MultiSelect.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 |
MultiSelect.Trigger
Combines MultiSelect.TriggerPrimitive, MultiSelect.ValuePrimitive, and MultiSelect.TriggerIconPrimitive into a single part that shows the selected values 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 |
MultiSelect.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 |
MultiSelect.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 |
MultiSelect.ValuePrimitive
Shows the selected values inside the trigger as badges, using each 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 |
placeholder? | - | ReactNode |
render? | - | ReactElementfunction |
MultiSelect.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 |
MultiSelect.Popup
Combines MultiSelect.PortalPrimitive, MultiSelect.PositionerPrimitive, and MultiSelect.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<MultiSelectPortalPrimitive.Props> |
positionerElement? | - | ReactElement<MultiSelectPositionerPrimitive.Props> |
style? | - | React.CSSPropertiesfunction |
finalFocus? | - | booleanReact.RefObject<HTMLElement | null>function |
render? | - | ReactElementfunction |
MultiSelect.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 |
MultiSelect.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 |
MultiSelect.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 |
MultiSelect.Item
Combines MultiSelect.ItemPrimitive and MultiSelect.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 |
MultiSelect.ItemPrimitive
Option in the popup that the user can select or deselect. 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 |
MultiSelect.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 |
MultiSelect.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 |
MultiSelect.Group
Groups related options under a MultiSelect.GroupLabel. Renders a <div> element.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |
MultiSelect.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 |