@contentful/f36-multiselect v4.23.1
title: 'Multiselect' type: 'component' status: 'alpha' section: 'formComponents' slug: /components/multiselect/ github: 'https://github.com/contentful/forma-36/tree/main/packages/components/Multiselect' storybook: 'https://f36-storybook.contentful.com/?path=/story/components-multiselect--basic'
typescript: ./Multiselect.tsx,./MultiselectOption.tsx
Multiselect allows users to make a multi selection from a list of options. It has multiple optional features like a search.
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
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)
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
2 months ago
3 months ago
4 months ago
9 months ago
7 months ago
7 months ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago