ts
| Guidance | Practices |
|---|---|
| Do | Use for a moderate, finite set of options where multiple choices are needed. |
| Do | Enable search filtering when the list exceeds ~15 options. |
| Do | Enable select-all when most users will want all or nearly all options selected. |
| Don't | Use for single-value selection — use Selector instead. |
| Don't | Show more than ~20 options without enabling search. |
| Prop | Type | Description |
|---|---|---|
labelrequired | string | Label text for accessibility. |
optionsrequired | XDSMultiSelectorOptionType[] | Array of items — strings, objects with value/label/icon/disabled, dividers, or sections. |
valuerequired | string[] | Currently selected values. |
onChangerequired | (value: string[]) => void | Callback fired when the selection changes. |
changeAction | (value: string[]) => void | Promise<void> | Async action on change. Fires after onChange. |
placeholder | string (default: 'Select...') | Placeholder text shown when no value is selected. |
size | 'sm' | 'md' | 'lg' (default: 'md') | Size variant for the selector. |
triggerDisplay | 'count' | 'labels' | 'badges' (default: 'count') | How to display selected items in the trigger. |
maxBadges | number (default: 3) | Maximum badges to show before "+N". Only for triggerDisplay="badges". |
hasSelectAll | boolean | Whether to show a select-all checkbox. |
selectAllLabel | string (default: 'Select all') | Label for the select-all checkbox. |
hasSearch | boolean | Whether to show a search input for filtering options. |
searchPlaceholder | string (default: 'Search...') | Placeholder text for the search input. |
isDisabled | boolean | Disables the selector. |
isLabelHidden | boolean | Visually hides the label while keeping it accessible. |
description | string | Helper text displayed below the label. |
isOptional | boolean | Marks the field as optional. |
isRequired | boolean | Marks the field as required. |
isLoading | boolean | Shows a loading spinner in the trigger. |
status | {type: 'error' | 'warning' | 'success', message?: string} | Validation status with an optional message. |
children | (option: XDSMultiSelectorOptionData) => ReactNode | Custom render function for each option in the dropdown. |
xstyle | StyleXStyles | StyleX styles for layout customization. Must be a stylex.create() value. |