@choice-ui
DocsComponentsTokens

MultiSelect

A multi-select dropdown component that allows users to select multiple options from a list

Storybook@choice-ui/multi-selectView Source

Installation

Terminal
pnpm add @choice-ui/multi-select

Import

Component.tsx
import { MultiSelect, MultiSelectTrigger, type MultiSelectProps, type MultiSelectTriggerProps } from "@choice-ui/multi-select"

Basic

Basic: The simplest usage of MultiSelect.
Features:
- Multiple selection with chip-based display - Individual item removal - Keyboard navigation support - Standard dropdown positioning - Controlled selection state

Selected Values

Count: 2
Values: [option-2, option-4]

Disabled

Disabled: Demonstrates disabled MultiSelect functionality.
Features:
- Disabled component prevents interaction - Visual feedback for disabled state - Selected values remain visible - Useful for conditional availability

Component State

Status: Disabled
Selected: option-2, option-4

Disabled Items

DisabledItems: Demonstrates disabled items in MultiSelect.
Features:
- Individual items can be disabled - Disabled items cannot be selected - Visual feedback for disabled items - Maintains keyboard navigation flow

Large Size

LargeSize: Demonstrates MultiSelect with large size variant.
Features:
- Large trigger size - Large menu items - Consistent sizing across components - Better visibility and touch targets

Selected Values

Size: Large
Count: 2
Values: [option-1, option-3]

Light Variant

LightVariant: Demonstrates MultiSelect with light variant styling.
Features:
- Light variant visual style - Standard selection functionality - Chip-based display - Consistent with light theme

With Icons

WithIcons: Demonstrates MultiSelect with icons and complex data.
Features:
- Icons displayed in menu items - Icons shown in selected chips - Complex data structures support - Maximum selection limit
Use cases:
- Field type selection - Category selection with icons - Visual option identification

Selected Field Types

Attachment Field(attachment)
Count Field(count)

With Labels And Dividers

WithLabelsAndDividers: Demonstrates MultiSelect with labels and dividers for organization.
Features:
- Section labels for grouping - Visual dividers for separation - Better menu organization - Hierarchical menu structure
Use cases:
- Plan selection with categories - Grouped option lists - Complex menu structures

Selected Plans

basic-1 → Basic - Starter
premium-1 → Premium - Business

Long List

LongList: Demonstrates MultiSelect with a long list of options and performance optimization.
Features:
- Long list of options (100 items) - Automatic scrolling when content exceeds height - Scroll arrows for navigation - Performance optimization for large lists - Maximum selection limit
Use cases:
- City/region selectors - Long option lists - Large dataset selection

Selected Cities

Count: 3
city-25→Oklahoma City 25
city-50→Tampa 50
city-75→St. Petersburg 75

With Limits

WithLimits: Demonstrates MultiSelect with maximum and minimum selection limits.
Features:
- Maximum selection limit (prevents selecting more) - Minimum selection limit (prevents removing below threshold) - Visual feedback for limit constraints - Selection state validation
Use cases:
- Required field selection - Limited choice scenarios - Form validation requirements

Selection Status

Count: 1
Can add more: Yes
Can remove: No

Exclusive Options

ExclusiveOptions: Demonstrates exclusive options with group and global exclusivity.
Features:
- Group exclusive (exclusiveIndex > 0): Groups mutually exclusive, multiple within group allowed - Global exclusive (exclusiveIndex = -1): Clears all other options - No constraint (exclusiveIndex = undefined): No exclusive constraint - Automatic clearing of conflicting selections
Exclusive Options Rules:
- Group 1 (A, B, C): Can select multiple within group - Group 2 (D, E, F): Can select multiple within group - Groups are mutually exclusive (selecting Group 2 clears Group 1) - Option G: Global exclusive (clears all others) - Options H, I: No constraints (but cleared when selecting constrained options)

Close On Select

CloseOnSelect: Demonstrates controlling whether the menu closes when selecting options.
Features:
- closeOnSelect=false: Menu stays open after selecting options (default behavior) - closeOnSelect=true: Menu closes after each selection - Side-by-side comparison of both behaviors - Better UX for multiple selections
Use cases:
- Quick multi-selection (keep open) - Single selection scenarios (close on select)

Validation Messages

ValidationMessages: Demonstrates validation messages for selection constraints.
Features:
- Shows validation messages when constraints are violated - Customizable messages via i18n prop - Auto-dismiss after 3 seconds - showValidationMessage prop to control display - Custom vs default message comparison
Use cases:
- Form validation feedback - User guidance for constraints - Internationalization support

Selected Values

Count: 0
Values: []

Max Chips

MaxChips: Demonstrates limiting the number of visible chips in the trigger.
Features:
- Maximum number of visible chips - Overflow indicator when limit exceeded - Compact display for many selections - Better UI for space-constrained layouts
Use cases:
- Narrow input fields - Mobile interfaces - Space-efficient designs

Chip Variant

ChipVariant: Demonstrates different chip visual variants.
Features:
- Multiple chip variants (default, accent, success) - Dynamic variant selection - Visual distinction for selected items - Consistent styling across variants
Use cases:
- Status-based selection - Category differentiation - Visual hierarchy

Custom Chip

CustomChip: Demonstrates custom chip rendering with personalized styling.
Features:
- Custom chip appearance with custom colors - Custom delete button styling - Emoji-based visual indicators - Maintains all standard functionality
Use cases:
- Branded interfaces - Themed applications - Enhanced visual appeal
Selected: 2 items

Empty

Empty: Demonstrates empty state display when no options are available.
Features:
- Show custom empty message when options list is empty - Useful for async loading or filtered results scenarios

API reference

MultiSelectPropsTypeDefault
chipVariant
undefined
|
"default"
|
"rest"
|
"accent"
|
"success"
 -
className
string
|
undefined
 -
closeOnSelect
boolean
|
undefined
 -
disabled
boolean
|
undefined
 -
focusManagerProps
FloatingFocusManagerProps
|
undefined
 -
getDisplayValue
((value: string) => string)
|
undefined
 -
i18n
{ maxSelectionMessage?: ((maxSelection: number) => string)
|
undefined; minSelectionMessage?: ((minSelection: number) => string)
|
undefined; }
|
undefined
 -
matchTriggerWidth
boolean
|
undefined
 -
maxChips
number
|
undefined
 -
maxSelection
number
|
undefined
 -
minSelection
number
|
undefined
 -
onChange
((values: string[]) => void)
|
undefined
 -
onOpenChange
((open: boolean) => void)
|
undefined
 -
open
boolean
|
undefined
 -
placeholder
string
|
undefined
 -
placement
undefined
|
"top"
|
"right"
|
"bottom"
|
"left"
|
"top-start"
|
"top-end"
|
"right-start"
|
"right-end"
|
"bottom-start"
|
"bottom-end"
|
"left-start"
|
"left-end"
 -
portalId
string
|
undefined
 -
readOnly
boolean
|
undefined
 -
renderChip
((props: { disabled?: boolean
|
undefined; displayValue: string; index: number; onRemove?: ((e: MouseEvent<HTMLButtonElement, MouseEvent>) => void)
|
undefined; value: string; }) => ReactNode)
|
undefined
 -
root
HTMLElement
|
null
|
undefined
 -
showValidationMessage
boolean
|
undefined
 -
size
undefined
|
"default"
|
"large"
 -
values
string[]
|
undefined
 -
variant
undefined
|
"default"
|
"light"
|
"reset"
 -
MultiSelectTriggerPropsTypeDefault
size
undefined
|
"default"
|
"large"
 -
disabled
boolean
|
undefined
 -
open
boolean
|
undefined
 -
placeholder
string
|
undefined
 -
readOnly
boolean
|
undefined
 -
getDisplayValue
((value: string) => string)
|
undefined
 -
maxChips
number
|
undefined
 -
onRemove
((value: string) => void)
|
undefined
 -
renderChip
((props: { disabled?: boolean
|
undefined; displayValue: string; index: number; onRemove?: ((e: MouseEvent<HTMLButtonElement, MouseEvent>) => void)
|
undefined; value: string; }) => ReactNode)
|
undefined
 -
suffixElement
ReactNode -
valueDisabledMap
Record<string, boolean>
|
undefined
 -
values
string[]
|
undefined
 -
variant
undefined
|
"default"
|
"accent"
|
"success"
|
"rest"
 -
ref
((instance: HTMLDivElement
|
null) => void)
|
RefObject<HTMLDivElement>
|
null
|
undefined
 -