Multiple Selector
Fast, composable, fully-featured multiple selector for React.
About
This component is inspired by Fancy Multi Select
and includes additional features such as asynchronous search(with debounce), maximum selected count, grouping, and a creatable selector ...etc.
It is built on top of Command
component in shadcn-ui, which is base on cmdk
.
Installation
Install the package if you do not have it.
npx shadcn-ui@latest add command badge
Copy and paste the following code into your project.
'use client';
import * as React from 'react';
import { X } from 'lucide-react';
import {
Command,
CommandGroup,
CommandItem,
CommandEmpty,
CommandList,
} from '@/components/ui/command';
import { Command as CommandPrimitive } from 'cmdk';
import { useEffect } from 'react';
import { Badge } from '@/components/ui/badge';
import { cn } from '@/lib/utils';
export interface Option {
value: string;
label: string;
disable?: boolean;
fixed?: boolean;
[key: string]: string | boolean | undefined;
}
export interface GroupOption {
[key: string]: Option[];
}
interface GroupMultipleSelectorProps {
value?: Option[];
options?: Option[];
placeholder?: string;
/** loading component */
loadingIndicator?: React.ReactNode;
/** empty component */
emptyIndicator?: React.ReactNode;
/** debounce time for async search */
delay?: number;
/** async search */
onSearch?: (value: string) => Promise<Option[]>;
onChange?: (options: Option[]) => void;
maxSelected?: number;
onMaxSelected?: (maxLimit: number) => void;
hidePlaceholderWhenSelected?: boolean;
disabled?: boolean;
groupBy?: string;
className?: string;
badgeClassName?: string;
selectFirstItem?: boolean;
creatable?: boolean;
}
export function useDebounce<T>(value: T, delay?: number): T {
const [debouncedValue, setDebouncedValue] = React.useState<T>(value);
useEffect(() => {
const timer = setTimeout(() => setDebouncedValue(value), delay || 500);
return () => {
clearTimeout(timer);
};
}, [value, delay]);
return debouncedValue;
}
function transToGroupOption(options: Option[], groupBy?: string) {
if (options.length === 0) {
return {};
}
if (!groupBy) {
return {
'': options,
};
}
const groupOption: GroupOption = {};
options.forEach((option) => {
const key = (option[groupBy] as string) || '';
if (!groupOption[key]) {
groupOption[key] = [];
}
groupOption[key].push(option);
});
return groupOption;
}
export default function GroupMultipleSelector({
value,
onChange,
placeholder,
options: arrayOptions = [],
delay,
onSearch,
loadingIndicator,
emptyIndicator,
maxSelected = Number.MAX_SAFE_INTEGER,
onMaxSelected,
hidePlaceholderWhenSelected,
disabled,
groupBy,
className,
badgeClassName,
selectFirstItem = true,
creatable = false,
}: GroupMultipleSelectorProps) {
const inputRef = React.useRef<HTMLInputElement>(null);
const [open, setOpen] = React.useState(false);
const [isLoading, setIsLoading] = React.useState(false);
const [selected, setSelected] = React.useState<Option[]>(value || []);
const [options, setOptions] = React.useState<GroupOption>(
transToGroupOption(arrayOptions, groupBy),
);
const [inputValue, setInputValue] = React.useState('');
const debouncedSearchTerm = useDebounce(inputValue, delay || 500);
const handleUnselect = React.useCallback(
(option: Option) => {
const newOptions = selected.filter((s) => s.value !== option.value);
setSelected(newOptions);
onChange?.(newOptions);
},
[selected],
);
const handleKeyDown = React.useCallback(
(e: React.KeyboardEvent<HTMLDivElement>) => {
const input = inputRef.current;
if (input) {
if (e.key === 'Delete' || e.key === 'Backspace') {
if (input.value === '' && selected.length > 0) {
handleUnselect(selected[selected.length - 1]);
}
}
// This is not a default behaviour of the <input /> field
if (e.key === 'Escape') {
input.blur();
}
}
},
[selected],
);
useEffect(() => {
if (value) {
setSelected(value);
}
}, [value]);
useEffect(() => {
const exec = async () => {
if (!debouncedSearchTerm || !onSearch) return;
setIsLoading(true);
const res = await onSearch?.(debouncedSearchTerm);
setOptions(transToGroupOption(res, groupBy));
setIsLoading(false);
};
void exec();
}, [debouncedSearchTerm]);
const selectables = React.useMemo<GroupOption>(
() => removePickedOption(options, selected),
[options, selected],
);
return (
<Command
onKeyDown={handleKeyDown}
className="overflow-visible bg-transparent"
shouldFilter={!onSearch} // when onSearch is provided, we don't want to filter the options.
>
<div
className={cn(
'group rounded-md border border-input px-3 py-2 text-sm ring-offset-background focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2',
className,
)}
>
<div className="flex flex-wrap gap-1">
{selected.map((option) => {
return (
<Badge
key={option.value}
className={cn(
'data-[disabled]:bg-muted-foreground data-[disabled]:text-muted data-[disabled]:hover:bg-muted-foreground',
'data-[fixed]:bg-muted-foreground data-[fixed]:text-muted data-[fixed]:hover:bg-muted-foreground',
badgeClassName,
)}
data-fixed={option.fixed}
data-disabled={disabled}
>
{option.label}
<button
className={cn(
'ml-1 rounded-full outline-none ring-offset-background focus:ring-2 focus:ring-ring focus:ring-offset-2',
(disabled || option.fixed) && 'hidden',
)}
onKeyDown={(e) => {
if (e.key === 'Enter') {
handleUnselect(option);
}
}}
onMouseDown={(e) => {
e.preventDefault();
e.stopPropagation();
}}
onClick={() => handleUnselect(option)}
>
<X className="h-3 w-3 text-muted-foreground hover:text-foreground" />
</button>
</Badge>
);
})}
{/* Avoid having the "Search" Icon */}
<CommandPrimitive.Input
ref={inputRef}
value={inputValue}
disabled={disabled}
onValueChange={setInputValue}
onBlur={() => setOpen(false)}
onFocus={() => setOpen(true)}
placeholder={hidePlaceholderWhenSelected && selected.length !== 0 ? '' : placeholder}
className="ml-2 flex-1 bg-transparent outline-none placeholder:text-muted-foreground"
/>
</div>
</div>
<div className="relative mt-2">
{open && (
<CommandList className="absolute top-0 z-10 w-full rounded-md border bg-popover text-popover-foreground shadow-md outline-none animate-in">
{isLoading ? (
<>{loadingIndicator}</>
) : (
<>
<CommandEmpty>{emptyIndicator}</CommandEmpty>
{/* for async search that showing emptyIndicator */}
{onSearch && !creatable && Object.keys(options).length === 0 && (
<CommandItem value="-" disabled>
{emptyIndicator}
</CommandItem>
)}
{!selectFirstItem && <CommandItem value="-" className="hidden" />}
{/* for normal creatable. */}
{creatable && inputValue.length > 0 && !onSearch && (
<CommandItem
value={inputValue}
onSelect={(value: string) => {
if (selected.length >= maxSelected) {
onMaxSelected?.(selected.length);
return;
}
setInputValue('');
const newOptions = [...selected, { value, label: value }];
setSelected(newOptions);
onChange?.(newOptions);
}}
>{`Create "${inputValue}"`}</CommandItem>
)}
{/* for async search use. avoid showing creatable item before loading */}
{creatable && debouncedSearchTerm.length > 0 && onSearch && !isLoading && (
<CommandItem
value={inputValue}
onSelect={(value: string) => {
if (selected.length >= maxSelected) {
onMaxSelected?.(selected.length);
return;
}
setInputValue('');
const newOptions = [...selected, { value, label: value }];
setSelected(newOptions);
onChange?.(newOptions);
}}
>{`Create "${inputValue}"`}</CommandItem>
)}
{Object.entries(selectables).map(([key, dropdowns]) => (
<CommandGroup key={key} heading={key} className="h-full overflow-auto">
<>
{dropdowns.map((option) => {
return (
<CommandItem
key={option.value}
value={option.value}
disabled={option.disable}
onMouseDown={(e) => {
e.preventDefault();
e.stopPropagation();
}}
onSelect={() => {
if (selected.length >= maxSelected) {
onMaxSelected?.(selected.length);
return;
}
setInputValue('');
const newOptions = [...selected, option];
setSelected(newOptions);
onChange?.(newOptions);
}}
className={cn(
'cursor-pointer',
option.disable && 'cursor-default text-muted-foreground',
)}
>
{option.label}
</CommandItem>
);
})}
</>
</CommandGroup>
))}
</>
)}
</CommandList>
)}
</div>
</Command>
);
}
function removePickedOption(groupOption: GroupOption, picked: Option[]) {
const cloneOption = JSON.parse(JSON.stringify(groupOption)) as GroupOption;
for (const [key, value] of Object.entries(cloneOption)) {
cloneOption[key] = value.filter((val) => !picked.find((p) => p.value === val.value));
}
return cloneOption;
}
Update the import paths to match your project setup.
Usage
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.
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.
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
Maximum Selected Count
Following example is set to 3. The default of max selected is Number.MAX_SAFE_INTEGER
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
Properties
Property | Type | Default |
---|---|---|
value | Option[] | [] |
options | Option[] | [] |
placeholder | string | |
onChange | (options: Option[]) => void | |
disabled | boolean | false |
delay | number | 500 |
onSearch | (value: string) => Promise<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 |