Multiple Selector

A multi-select input with async search, grouping, and creatable options.

@spectrumui/multiple-selector-demo

Installation

Usage

Disable Option

@spectrumui/multiple-selector-with-disable-options

Disabled

@spectrumui/multiple-selector-disabled

nextjs

React

Remix

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.

@spectrumui/multiple-selector-no-default-select

Controlled Component

@spectrumui/multiple-selector-controlled

Your selection:

Hide Clear All Button

@spectrumui/multiple-selector-hide-clear-all

Creatable Selector

Create option when there is no option matched.

@spectrumui/multiple-selector-creatable

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.

@spectrumui/multiple-selector-with-async-search

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.

@spectrumui/multiple-selector-with-async-search-and-onfocus

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.

@spectrumui/multiple-selector-with-async-search-and-creatable

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.

@spectrumui/multiple-selector-with-async-search-and-creatable-and-group

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.

@spectrumui/multiple-selector-with-sync-search

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.

@spectrumui/multiple-selector-manually-controlled

Grouped

Grouping options by specific key of object

@spectrumui/multiple-selector-with-group

Maximum Selected Count

Following example is set to 3. The default of max selected is Number.MAX_SAFE_INTEGER

@spectrumui/multiple-selector-max-selected

Maximum Text Length

Following example is set to 5.

@spectrumui/multiple-selector-max-text-length

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

@spectrumui/multiple-selector-no-placeholder-when-selected

Fixed Options

Provide fixed: true in your value

@spectrumui/multiple-selector-fixed-option

nextjs

React

ref

@spectrumui/multiple-selector-ref

CommandProps and CommandInputProps Customization

@spectrumui/multiple-selector-commandprops

Is focus? false

You can opencommand description and input description to check the customization of aria-description.

Form

@spectrumui/multiple-selector-with-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, `defaultOptions` is a better choice.
`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 `onChange` will be called.
`disabled`	`boolean`	`false`	disabled select.
`delay`	`number`	`500`	The debounce time. only works with `onSearch`.
`triggerSearchOnFocus`	`boolean`	`false`	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.
`onSearch`	`(value: string) => Promise<Option[]>`	-	Load options from a remote source when user types. You can provide `delay` to set debounce time.
`onSearchSync`	`(value: string) => Option[]`	-	Load options from a local source when user types. This will not show `loadingIndicator` even if you provide it. The rest props are the same as async search. i.e.: `creatable`, `groupBy`, `delay`.
`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 `onMaxSelected` will be called.
`loadingIndicator`	`ReactNode`	-	Show the loading component when `onSearch` is not finished.
`emptyIndicator`	`ReactNode`	-	Show the empty component when there is no options.
`selectFirstItem`	`boolean`	`true`	First item selected is a default behavior by `cmdk`. That is why the default is `true`. This is a workaround solution by add a dummy item. Learn more about the `issue`.
`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 `Command`
`inputProps`	`Omit<React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>,'value' \| 'placeholder' \| 'disabled' >`	-	props of `CommandInput`
`hideClearAllButton`	`boolean`	-	Hide the `Clear All` button.