Multiple Selector
Overview
A multi-select input with async search, grouping, and creatable options.
This form component is intended for interfaces that need a multi-select input with async search, grouping, and creatable options, authentication flows, and settings forms. Its implementation is provided as editable source so the final behavior and styling stay inside your project.
Technologies
Detected package dependencies: react-hook-form, zod, @hookform/resolvers.
Installation
Usage
Disable Option
Disabled
Disable First Item selected
The first item selected is a default behavior by cmdk and there is no way to control it. You can learn more about the issue.
Here is a workaround solution: by adding a dummy item.
Controlled Component
Your selection:
Hide Clear All Button
Creatable Selector
Create option when there is no option matched.
Async Search with Debounce
The async search is debounced by default. The delay time is 500ms if you do not provide it.
You can provide delay to customize the time. The delay prop only works with onSearch.
The empty text will not trigger the search. On the other hand, if the search had been triggered, and user delete all the texts, it will not trigger the search again and keep the current options with empty text.
Is request been triggered? false
Trigger Search on Focus
Only works with onSearch prop. Trigger search when onFocus.
For example, when user click on the input, it will trigger the search to get initial options.
The empty text will trigger the search.
Is request been triggered? false
Async Search with Debounce and Creatable
If you combine the async search and creatable, you can create option when there is no option matched.
Is request been triggered? false
Async Search and Creatable and Group
If you combine the async search and creatable and group, you can still create option when there is no option matched.
Is request been triggered? false
Sync Search without loading indicator
Sync search is for search locally without any request to the server. This will not show loading indicator even if you provide it. The rest props are the same as async search. i.e.: creatable, groupBy, delay.
Sync search
Creatable
GroupBy
Debounce
Manually Controlled Options
If you want to controlled options yourself, you can provide options prop.
Otherwise, defaultOptions is a better choice.
Grouped
Grouping options by specific key of object
Maximum Selected Count
Following example is set to 3. The default of max selected is Number.MAX_SAFE_INTEGER
Maximum Text Length
Following example is set to 5.
Hide Placeholder When Selected
If you would like to work as a normal input that hide the placeholder when there are options selected.
Just set hidePlaceholderWhenSelected to true
Fixed Options
Provide fixed: true in your value
ref
CommandProps and CommandInputProps Customization
Is focus? false
You can opencommand description and input description to check the customization of aria-description.
Form
Properties
| Prop | Type | Default | Description |
|---|---|---|---|
value | Option[] | [] | Selected Value. |
defaultOptions | Option[] | [] | The dropdown options for most case. |
options | Option[] | - | The dropdown options that you can control yourself. In most case, |
placeholder | string | | The input placeholder. |
hidePlaceholderWhenSelected | boolean | false | Hide the placeholder when there are options selected. |
onChange | (options: Option[]) => void | - | When you select or remove an option, the |
disabled | boolean | false | disabled select. |
delay | number | 500 | The debounce time. only works with |
triggerSearchOnFocus | boolean | false | Only works with For example, when user click on the input, it will trigger the search to get initial options. |
onSearch | (value: string) => Promise<Option[]> | - | Load options from a remote source when user types. You can provide |
onSearchSync | (value: string) => Option[] | - | Load options from a local source when user types. This will not show |
creatable | boolean | false | Create option when there is no option matched. |
groupBy | string | - | Group the options base on provided key. |
maxSelected | number | Number.MAX_SAFE_INTEGER | Limit the maximum number of selected options. |
onMaxSelected | (maxLimit: number) => void | - | When the number of selected options exceeds the limit, the |
loadingIndicator | ReactNode | - | Show the loading component when |
emptyIndicator | ReactNode | - | Show the empty component when there is no options. |
selectFirstItem | boolean | true | First item selected is a default behavior by This is a workaround solution by add a dummy item. Learn more about the |
className | string | - | Customize the style by adding tailwind. |
badgeClassName | string | - | Customize the style by adding tailwind for the selected options (badge). |
ref | React.RefObject<MultipleSelectorRef> | - | Pass a ref to the input element and retrieve the selected value as well. |
commandProps | React.ComponentPropsWithoutRef<typeof Command> | - | props of |
inputProps | Omit<React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>,'value' | 'placeholder' | 'disabled' > | - | props of |
hideClearAllButton | boolean | - | Hide the |
Use cases
- interfaces that need a multi-select input with async search, grouping, and creatable options
- authentication flows
- settings forms
Features
- Copy-paste source that remains in your repository
- TypeScript source included with the component
- Tailwind CSS classes editable in the component source
- shadcn/ui dependencies: form
- Spectrum UI registry dependencies: @spectrumui/multiple-selector-dependencies, @spectrumui/inline-code, @spectrumui/heading-with-anchor, @spectrumui/loading-button-dependencies, @spectrumui/use-toast, @spectrumui/loading-button
Accessibility
- The source includes ARIA attributes or roles; preserve them when customizing the component.
- The source includes keyboard event handling; verify it alongside pointer behavior.
- Test focus order, keyboard operation, labels, contrast, and screen-reader output in the final application context.
Customization
- Edit the Tailwind utility classes in the copied source to match your spacing, color, and typography tokens.
- Use the documented className surface for local layout adjustments, then edit the source for structural changes.
Related components
Topic guides
See how this component fits into broader interface patterns, implementation decisions, and working examples.
Multiple Selector FAQ
Is Multiple Selector free to use in commercial projects?
Yes. The public Multiple Selector source is available under the Apache License 2.0, including for commercial use, subject to the LICENSE terms.
How do I install Multiple Selector?
Run npx shadcn@latest add @spectrumui/multiple-selector-demo or npx shadcn@latest add @spectrumui/multiple-selector-with-disable-options or npx shadcn@latest add @spectrumui/multiple-selector-disabled or npx shadcn@latest add @spectrumui/multiple-selector-no-default-select or npx shadcn@latest add @spectrumui/multiple-selector-controlled or npx shadcn@latest add @spectrumui/multiple-selector-hide-clear-all or npx shadcn@latest add @spectrumui/multiple-selector-creatable or npx shadcn@latest add @spectrumui/multiple-selector-with-async-search or npx shadcn@latest add @spectrumui/multiple-selector-with-async-search-and-onfocus or npx shadcn@latest add @spectrumui/multiple-selector-with-async-search-and-creatable or npx shadcn@latest add @spectrumui/multiple-selector-with-async-search-and-creatable-and-group or npx shadcn@latest add @spectrumui/multiple-selector-with-sync-search or npx shadcn@latest add @spectrumui/multiple-selector-manually-controlled or npx shadcn@latest add @spectrumui/multiple-selector-with-group or npx shadcn@latest add @spectrumui/multiple-selector-max-selected or npx shadcn@latest add @spectrumui/multiple-selector-max-text-length or npx shadcn@latest add @spectrumui/multiple-selector-no-placeholder-when-selected or npx shadcn@latest add @spectrumui/multiple-selector-fixed-option or npx shadcn@latest add @spectrumui/multiple-selector-ref or npx shadcn@latest add @spectrumui/multiple-selector-commandprops or npx shadcn@latest add @spectrumui/multiple-selector-with-form or npx shadcn@latest add command badge. The page also exposes the source for manual installation.
Does Multiple Selector require Motion?
No Motion dependency was detected in the documented source or registry entry for Multiple Selector.
Does Multiple Selector use shadcn/ui or Radix UI?
Multiple Selector uses the form shadcn/ui dependencies.
Can I use Multiple Selector in Next.js?
The documented React source is used in this Next.js application. Keep its use client directive when copying it into the App Router. Install the detected dependencies and verify any application-specific data or image configuration.
What accessibility checks should I run for Multiple Selector?
The source includes ARIA markup, keyboard handlers. Test the finished interface with keyboard and screen-reader workflows.