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

1

Install the package if you do not have it.

npx shadcn-ui@latest add command badge
2

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;
  maxTextLength?: number;
}

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,
                                                maxTextLength=Number.MAX_SAFE_INTEGER,
}: 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 CreatableItem = () => {
    if (!creatable) return undefined;

    const Item = (<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 normal creatable
    if (!onSearch && inputValue.length > 0) {
      return Item;
    }

    // for async search creatable. avoid showing creatable item before loading at first.
    if (onSearch && debouncedSearchTerm.length > 0 && !isLoading) {
      return Item;
    }

    return undefined;
  }

  const EmptyItem = () => {
    if (!emptyIndicator) return undefined;

    // for async search that showing emptyIndicator
    if (onSearch && !creatable && Object.keys(options).length === 0) {
     return (<CommandItem value="-" disabled>
       {emptyIndicator}
     </CommandItem>);
    }

    return (<CommandEmpty>{emptyIndicator}</CommandEmpty>);
  }

  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"
            maxLength={maxTextLength}
          />
        </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}</>
            ) : (
              <>
                {EmptyItem()}
                {CreatableItem()}
                {!selectFirstItem && <CommandItem value="-" className="hidden" />}
                {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;
}
3

Update the import paths to match your project setup.

Usage

Disable Option

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.

Controlled Component

Your selection:

Creatable Selector

Create option when there is no option matched.

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

If you combine the async search and creatable, you can create option when there is no option matched.

Is request been triggered? false

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

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. 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

Fixed Options

Provide fixed: true in your value

nextjs
React

Form

Properties

PropertyTypeDefault
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
maxTextLength
number
Number.MAX_SAFE_INTEGER
onMaxSelected
(maxLimit: number) => void
loadingIndicator
ReactNode
emptyIndicator
ReactNode
selectFirstItem
boolean
true
className
string
badgeClassName
string
Buy Me A Coffee