About
This component is inspired by Fancy Multi Select and includes additional features that React-Select offers.
It is built on top of Command component in shadcn-ui, which is base on cmdk.
- Async search with debounce.
- Creatable selector — create option when there is no option matched.
- Grouping functionality.
- Working with
react-hook-form. - Customize your own loading spinner and empty indicator by giving props.
- Fixed options, maximum selected count, maximum input text length.
- Ability to disable the default selection of the first item.(see more about the issue)
Installation
Run the following command
pnpm dlx @shadext/cli add multiple-selector
Example
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 open console and search command description and input description to check the customization of aria-description.
Form
API Reference
Props
The SmartDatetimeInput component accepts the following props:
| value | Option[] | [] |
|---|---|---|
defaultOptions | Option[] | [] |
options | Option[] | |
placeholder | string | "" |
hidePlaceholderWhenSelected | boolean | false |
onChange | (options: Option[]) => void | |
disabled | boolean | false |
delay | number | 500 |
triggerSearchOnFocus | boolean | false |
onSearch | (value: string) => Promise<Option[]> | |
onSearchSync | (value: string) => Option[] | |
creatable | boolean | false |
groupBy | string | |
maxSelected | number | Number.MAX_SAFE_INTEGER |
onMaxSelected | (maxLimit: number) => void | |
loadingIndicator | ReactNode | |
emptyIndicator | ReactNode | |
selectFirstItem | boolean | true |
className | string | |
badgeClassName | string | |
ref | React.RefObject<MultipleSelectorRef> | |
commandProps | React.ComponentPropsWithoutRef<typeof Command> | |
inputProps | Omit<React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>, "value" | "placeholder" | "disabled"> | |
hideClearAllButton | boolean |