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
MultiSelect 복합 컴포넌트의 루트. 사용자가 팝업의 목록에서 여러 옵션을 고를 수 있습니다. 선택된 값과 열림 상태를 관리하며 size, invalid, placeholder를 파트에 전달합니다. 자체 HTML 요소를 렌더링하지 않습니다.
| 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
MultiSelect.TriggerPrimitive, MultiSelect.ValuePrimitive, MultiSelect.TriggerIconPrimitive를 하나의 파트로 합쳐 선택된 값과 쉐브런 아이콘을 표시합니다. <button> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
disabled? | - | boolean |
nativeButton? | true | boolean |
render? | - | ReactElementfunction |
MultiSelect.TriggerPrimitive
클릭하면 팝업을 여는 버튼. <button> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
disabled? | - | boolean |
nativeButton? | true | boolean |
render? | <button /> | ReactElementfunction |
MultiSelect.TriggerIconPrimitive
팝업을 열 수 있음을 나타내는 트리거 안의 쉐브런 아이콘. <span> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |
MultiSelect.ValuePrimitive
선택된 값을 트리거 안에 배지로 표시합니다. 각 배지에는 items의 항목 레이블을 쓰며, 아무것도 선택되지 않았으면 플레이스홀더를 표시합니다. <span> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
children? | - | ReactNodefunction |
placeholder? | - | ReactNode |
render? | - | ReactElementfunction |
MultiSelect.PlaceholderPrimitive
아무것도 선택되지 않았을 때 트리거에 표시되는 플레이스홀더 텍스트. <span> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |
MultiSelect.Popup
MultiSelect.PortalPrimitive, MultiSelect.PositionerPrimitive, MultiSelect.PopupPrimitive를 하나의 파트로 합칩니다. 포털이나 포지셔너를 바꾸려면 portalElement 또는 positionerElement를 사용하세요. <div> 요소로 렌더링됩니다.
| 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
일반적인 DOM 계층 밖에서 팝업을 렌더링하는 포털 컨테이너. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
container? | - | HTMLElementShadowRootReact.RefObject<HTMLElement | ShadowRoot | null>null |
render? | - | ReactElementfunction |
MultiSelect.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 |
MultiSelect.PopupPrimitive
옵션을 담는 팝업 패널. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
finalFocus? | - | booleanReact.RefObject<HTMLElement | null>function |
render? | - | ReactElementfunction |
MultiSelect.Item
MultiSelect.ItemPrimitive와 MultiSelect.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 |
MultiSelect.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 |
MultiSelect.ItemIndicatorPrimitive
항목이 선택되어 있는 동안 표시되는 체크 표시. <span> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
children? | - | ReactNode |
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
keepMounted? | - | boolean |
render? | - | ReactElementfunction |
MultiSelect.Separator
옵션 그룹을 시각적으로 구분하는 선. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
orientation? | horizontal | horizontalvertical |
render? | - | ReactElementfunction |
MultiSelect.Group
관련 옵션을 MultiSelect.GroupLabel 아래로 묶습니다. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |
MultiSelect.GroupLabel
옵션 그룹의 레이블. 보조기술이 읽어 줍니다. <div> 요소로 렌더링됩니다.
| Prop | Default | Type |
|---|---|---|
className? | - | stringfunction |
style? | - | React.CSSPropertiesfunction |
render? | - | ReactElementfunction |