Alpha component

Multiselect component is subject to major changes and is for experimentation purposes only. Not recommended for use in production software.

Multiselect allows users to make a multi selection from a list of options. It has multiple optional features like a search.


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


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

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

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.

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

Props (API reference)

Open in Storybook

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.


  • 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