Multiselect

Import

import { Multiselect } from '@contentful/f36-multiselect';

Examples

Basic usage

The Multiselect is a fully controlled form element and expects the selectable items as children via the compound component Multiselect.Option.

Properties are:

For the multiselect itself:

• currentSelection (optional but recommended): an array of the labels of selected options. This will give the user a hint that there are selected items. This is optional
• placeholder (optional): Label of the trigger button without selected elements
• startIcon (optional): Icon on the start of the trigger button
• isLoading: enables showing a loading animation while searching or loading results

Inherited propertys from Popover Component.

• listWidth (optional): auto or full
• listMaxHeight (optional): sets the maximum height of the list drawer, overflow will be scrolled

It also accepts refs for the toggle button, the searchInput and the list.

For the option:

• itemId: identifier for the element, used to link the label with the checkbox
• value: the actual value of the select option
• label: displayed label
• onSelectItem: This function is called when the user selects a option, it needs to be passed to the MultiselectOption
• isChecked (optional): controlls if a element is initially selected
• isDisabled (optional): controlls if a element is changeable

Hide code
function MultiselectBasicUsageExample() {
  const spaces = [
    'Travel Blog',
    'Finnance Blog',
    'Fitness App',
    'News Website',
    'eCommerce Catalogue',
    'Photo Gallery',
  ];

  // This `useState` is going to store the selected "space" so we can show it in the UI
  const [selectedSpaces, setSelectedSpaces] = React.useState([]);

  // This function will be called once the user selects an item in the list of options
  const handleSelectItem = (event) => {
    const { checked, value } = event.target;
    if (checked) {
      setSelectedSpaces((prevState) => [...prevState, value]);
    } else {
      const newSelectedSpaces = selectedSpaces.filter(
        (space) => space !== value,
      );
      setSelectedSpaces(newSelectedSpaces);
    }
  };

  return (
    <Stack flexDirection="column" alignItems="start">
      <Multiselect
        currentSelection={selectedSpaces}
        popoverProps={{ isFullWidth: true }}
      >
        {spaces.map((space) => {
          const val = space.toLowerCase().replace(/\s/g, '-');
          return (
            <Multiselect.Option
              key={`key-${val}}`}
              itemId={`space-${val}}`}
              value={space}
              label={space}
              onSelectItem={handleSelectItem}
              isChecked={selectedSpaces.includes(space)}
            />
          );
        })}
      </Multiselect>
    </Stack>
  );
}
Open in Playground

Searchable options

One optional feature of the Multiselect component is to allow filtering the list via a search field. To make it work, the onSearchValueChange callback function needs to be provided.

To enable searching the following properties have to be set.

• onSearchValueChange: Callbackfunction which enables the search field. This function needs to provide the search /filter algorithm
• searchPlaceholder (optional): placeholder for the search field
• noMatchesMessage (optional): message shown when search result is empty

Hide code
function MultiselectSearchExample() {
  const spaces = [
    'Travel Blog',
    'Finnance Blog',
    'Fitness App',
    'News Website',
    'eCommerce Catalogue',
    'Photo Gallery',
  ];

  const [selectedItems, setSelectedItems] = React.useState([]);
  const [filteredItems, setFilteredItems] = React.useState(spaces);

  const handleSearchValueChange = (event) => {
    const value = event.target.value;
    const newFilteredItems = spaces.filter((item) =>
      item.toLowerCase().includes(value.toLowerCase()),
    );
    setFilteredItems(newFilteredItems);
  };

  const handleSelectItem = (event) => {
    const { checked, value } = event.target;
    if (checked) {
      setSelectedItems((prevState) => [...prevState, value]);
    } else {
      const newSelectedItems = selectedItems.filter((space) => space !== value);
      setSelectedItems(newSelectedItems);
    }
  };

  return (
    <Stack flexDirection="column" alignItems="start">
      <Multiselect
        searchProps={{
          searchPlaceholder: 'Search spaces',
          onSearchValueChange: handleSearchValueChange,
        }}
        popoverProps={{ isFullWidth: true }}
        currentSelection={selectedItems}
      >
        {filteredItems.map((item, index) => {
          return (
            <Multiselect.Option
              value={item}
              label={item}
              onSelectItem={handleSelectItem}
              key={`${item}-${index}`}
              itemId={`${item}-${index}`}
              isChecked={selectedItems.includes(item)}
              isDisabled={item === 'eCommerce Catalogue'}
            />
          );
        })}
      </Multiselect>
    </Stack>
  );
}
Open in Playground

SelectAll Option

To offer a shortcut for selecting and deselecting all options, you can use the compound component SelectAll. This requires a callback function which needs to contain your implementation for selecting all options.

Hide code
function MultiselectSelectAllExample() {
  const spaces = React.useMemo(
    () => [
      'Travel Blog',
      'Finnance Blog',
      'Fitness App',
      'News Website',
      'eCommerce Catalogue',
      'Photo Gallery',
    ],
    [],
  );

  // This `useState` is going to store the selected "space" so we can show it in the UI
  const [selectedSpaces, setSelectedSpaces] = React.useState([]);

  // This function will be called once the user selects an item in the list of options
  const handleSelectItem = (event) => {
    const { checked, value } = event.target;
    if (checked) {
      setSelectedSpaces((prevState) => [...prevState, value]);
    } else {
      setSelectedSpaces((prevState) =>
        //its important to use prevState to avoid race conditions when using the state variable as reference.
        prevState.filter((space) => space !== value),
      );
    }
  };

  const toggleAll = (event) => {
    const { checked } = event.target;
    if (checked) {
      setSelectedSpaces(spaces);
    } else {
      setSelectedSpaces([]);
    }
  };

  const areAllSelected = React.useMemo(() => {
    // this can affect the app performance with a larger amount of data, consider changing it in your implementation
    return spaces.every((element) => selectedSpaces.includes(element));
  }, [selectedSpaces, spaces]);

  return (
    <Stack flexDirection="column" alignItems="start">
      <Multiselect
        currentSelection={selectedSpaces}
        popoverProps={{ isFullWidth: true }}
      >
        <Multiselect.SelectAll
          onSelectItem={toggleAll}
          isChecked={areAllSelected}
        />
        {spaces.map((space) => {
          const val = space.toLowerCase().replace(/\s/g, '-');
          return (
            <Multiselect.Option
              key={`key-${val}`}
              itemId={`space-${val}`}
              value={space}
              label={space}
              onSelectItem={handleSelectItem}
              isChecked={selectedSpaces.includes(space)}
            />
          );
        })}
      </Multiselect>
    </Stack>
  );
}
Open in Playground

Controlling from the Outside

In some cases it is desired to toggle the status of the popover drawer as well as to clear the search field from the parent. E.g. after a change has been applied. For this the Component offers two optional reference properties toggleRef and resetSearchRef

Hide code
function MultiselectReferenceExample() {
  const spaces = [
    'Travel Blog',
    'Finnance Blog',
    'Fitness App',
    'News Website',
    'eCommerce Catalogue',
    'Photo Gallery',
  ];

  const [selectedItems, setSelectedItems] = React.useState([]);
  const [filteredItems, setFilteredItems] = React.useState(spaces);
  const togglePopOverRef = React.useRef(null);
  const clearSearchFieldRef = React.useRef(null);

  const handleSearchValueChange = (event) => {
    const value = event.target.value;
    const newFilteredItems = spaces.filter((item) =>
      item.toLowerCase().includes(value.toLowerCase()),
    );
    setFilteredItems(newFilteredItems);
  };

  const handleSelectItem = (event) => {
    const { checked, value } = event.target;
    if (checked) {
      setSelectedItems((prevState) => [...prevState, value]);
    } else {
      const newSelectedItems = selectedItems.filter((space) => space !== value);
      setSelectedItems(newSelectedItems);
    }
  };

  const handleExtToggle = () => {
    togglePopOverRef.current.click();
  };

  const handleExtClearSearch = () => {
    clearSearchFieldRef.current.click();
  };

  return (
    <Stack flexDirection="column" alignItems="start">
      <Button onClick={handleExtToggle}>Toggle Popover</Button>
      <Button onClick={handleExtClearSearch}>Clear Search Field</Button>
      <Multiselect
        searchProps={{
          searchPlaceholder: 'Search spaces',
          onSearchValueChange: handleSearchValueChange,
          resetSearchRef: clearSearchFieldRef,
        }}
        popoverProps={{ isFullWidth: true, closeOnBlur: false }}
        currentSelection={selectedItems}
        toggleRef={togglePopOverRef}
      >
        {filteredItems.map((item, index) => {
          return (
            <Multiselect.Option
              value={item}
              label={item}
              onSelectItem={handleSelectItem}
              key={`${item}-${index}`}
              itemId={`${item}-${index}`}
              isChecked={selectedItems.includes(item)}
              isDisabled={item === 'eCommerce Catalogue'}
            />
          );
        })}
      </Multiselect>
    </Stack>
  );
}
Open in Playground

With component as children

You can render React components in the select options, but it's important to note that this makes it your own responsibility to highlight the matching part of the search term. To help with this there's the HighlightedItem component.

Hide code
function MultiselectSearchExample() {
  const spaces = [
    'Travel Blog',
    'Finnance Blog',
    'Fitness App',
    'News Website',
    'eCommerce Catalogue',
    'Photo Gallery',
  ];

  const [searchValue, setSearchValue] = React.useState('');
  const [selectedItems, setSelectedItems] = React.useState([]);

  const handleSearchValueChange = (event) => {
    const value = event.target.value;
    setSearchValue(value);
  };

  const handleSelectItem = (event) => {
    const { checked, value } = event.target;
    if (checked) {
      setSelectedItems((prevState) => [...prevState, value]);
    } else {
      const newSelectedItems = selectedItems.filter((space) => space !== value);
      setSelectedItems(newSelectedItems);
    }
  };

  return (
    <Stack flexDirection="column" alignItems="start">
      <Multiselect
        searchProps={{
          searchPlaceholder: 'Search spaces',
          onSearchValueChange: handleSearchValueChange,
        }}
        popoverProps={{ isFullWidth: true }}
        currentSelection={selectedItems}
      >
        {spaces
          .filter((item) =>
            item.toLowerCase().includes(searchValue.toLowerCase()),
          )
          .map((item, index) => {
            return (
              <Multiselect.Option
                value={item}
                onSelectItem={handleSelectItem}
                key={`${item}-${index}`}
                itemId={`${item}-${index}`}
                isChecked={selectedItems.includes(item)}
                isDisabled={item === 'eCommerce Catalogue'}
              >
                <Multiselect.HighlightedItem
                  item={item}
                  inputValue={searchValue}
                />{' '}
                <HelpCircleIcon size="tiny" />
              </Multiselect.Option>
            );
          })}
      </Multiselect>
    </Stack>
  );
}
Open in Playground

Content guidelines

• Multiselect placeholder should be short but descriptive.
• Multiselect options can come from a simple array of strings or more complex objects.
• Do not use the index position of the items in the filtered array for keys or ids, as they are going to change while filtering.
• Use any algorithm you like in order to search and filter. Depending on your implementation you can also generate a new request to your dataset based on the users input.

Accessibility

• When focussing the toggle button, the enter key opens it. The dropdown content automatically will be focussed
• Pressing the space bar toggles the checked state of an option and will trigger the onSelectItem callback function