Selectable
EuiSelectable aims to make the pattern of a selectable list (with or without search) consistent across implementations. It is the same concept used in EuiComboBox and EuiFilterGroup. This is not intended for primary navigation but can be used to simplify the construction of popover navigational menus; i.e. the spaces menu in the header. See EUI's in-depth guide on which selection component to use for more information.
The basics
At its simplest, EuiSelectable requires an array of options and an onChange handler which passes back the altered selectedOptions array. The children is a function that return the list and search nodes.
EuiSelectable offers the ability to exclude selections or include selections for some (mixed). Therefore, the checked property is one of undefined | 'on' | 'off' | 'mixed'.
'on' is the default for selected options when allowExclusions = false.
Searchable
To add a search component to the list, simply add the searchable prop. You can optionally pass in a searchProps object which will get passed down to the actual EuiFieldSearch used. In this example,onSearch will return a second parameter, enabling you to access the list of filtered items
The search is performed as a string match against the option.label unless a separate option.searchableLabel is provided.
Single selection
Selection can be restricted to a single option at a time with the singleSelection prop. Passing true allows for 0 or 1 option to be selected, while "always" requires 1 option to be selected at all times. The default value is false.
Options can be excluded
Adding allowExclusions allows cycling through the checked options (on -> off -> undefined).
Options can be mixed (indeterminate)
Setting an option to checked: “mixed” allows showing an indeterminate/mixed state. This state can only be set by the consuming application, and should typically be used to show that another state being controlled by the EuiSelectable has some, but not all, items selected.
When clicking a mixed option, the option will cycle to "on", and after that cycle between on -> off (if allowExclusions is true) -> undefined). Users cannot manually cycle back to mixed.
Messages and loading
The component comes with pre-composed messages for loading, empty, and no search result states. To display your own messages, pass loadingMessage, emptyMessage, errorMessage, or noMatchesMessage respectively. Alternatively, you can replace the entire list display with your own message for any state. In which case, we recommend wrapping your custom message in an EuiSelectableMessage component.
Sizing and containers
The component's children, list, search, are returned via the children function, which means you can wrap the indivial elements in anything you want.
Width and height
The width has been made to always be 100% of its container, including stretching the search input. When used inside of EuiPopover, we recommend setting a width (or min/max values) via CSS on the element containing the list to avoid expansion and contraction. By default, the height is capped at showing up to 7.5 items. It shows half of the last one to help indicate that there are more options to scroll to. To stretch the box to fill its container, pass 'full' to the height prop.
Flexbox
Be aware that display: flex with column layout is applied to the wrapping container. This is so that you can opt in to allow the height of the list stretch to fill its container. See the flyout example.
Truncation
EuiSelectable defaults to listProps.textWrap="truncate", which truncates long option text at the end of the string.
You can use listProps.truncationProps and almost any prop that EuiTextTruncate accepts to configure this behavior. This can be configured at the EuiSelectable level, as well as by each individual option.
Tooltips
If you have longer information that you need to make available to users outside of truncated text, one approach could be adding tooltip descriptions to individual options by passing toolTipContent.
You can additionally customize individual tooltip behavior by passing toolTipProps, which accepts any configuration that EuiToolTip accepts.
Rendering the options
There are two object properties you can add to enhance the content of your options, option.prepend and option.append. These will add nodes before and after the option label respectively. They will not be included in the searchable content as this only matches against the label property.
Selection icons
You can choose not to display the check and cross icons indicating selection by setting listProps.showIcons to false. This is useful for instances that navigate elsewhere on selection or hide their selected options from the list.
Group labels
An option is allowed to be passed that is just a header for the options that follow it. It takes no mouse handlers and renders similar to a title. Add one of these by setting the option.isGroupLabel to true.
Row height and virtualization
When virtualization is on, every row must be the same height in order for the list to know how to scroll to the selected or highlighted option. It applies the listProps.rowHeight (in pixels) directly to each option hiding any overflow.
If listProps.isVirtualized is set to false, each row will fit its content. You can also remove truncation by setting textWrap="wrap" when virtualization is off. Note that while this is useful for dynamic options, it can also be computationally expensive as all off-screen options will be rendered to the DOM. We do not recommend turning off virtualization for high numbers of options, but if you absolutely must do so, we suggest using methods such as async loading more options.
Custom content
While it is best to stick to the option.label, option.append, option.prepend and listProps.showIcons props, you can pass a custom renderOption function which will pass back the single option object and the searchValue to use for highlighting.
To provide data that can be used by the renderOption function that does not match the standard option API, use option.data which will make custom data available in the option parameter. See the secondaryContent configuration in the following example.
Also, if your custom content is taller than the default listProps.rowHeight of 32px tall, you will need to pass in a custom value to this prop.
Custom option matcher
When searching for options, EuiSelectable uses a partial equality string matcher by default, displaying all options whose labels include the searched string.
In rare cases, you may want to customize this behavior. You can do so by passing a custom option matcher function to the optionMatcher prop. The function must be of type EuiSelectableOptionMatcher and returntrue for options that should be visible for given search string.
Props
EuiSelectable
Prop | Description and type | Default value |
|---|---|---|
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop searchable# | Description and type Hooks up a search box to filter the list (boolean) boolean | Default value false |
Prop searchProps# | Description and type Passes props down to the Partial<EuiSelectableSearchProps<T>> | Default value |
Prop children# | Description and type Function that takes the (list: ReactElement<typeof EuiSelectableList | FunctionComponent<EuiSelectableMessageProps>, string | JSXElementConstructor<any>>, search: ReactElement<...>) => ReactNode | Default value |
Prop options# | Description and type Array of EuiSelectableOption objects. See #EuiSelectableOptionProps ExclusiveUnion<EuiSelectableGroupLabelOption<T>, EuiSelectableLIOption<T>>[] | Default value [] |
Prop onChange# | Description and type Passes back the altered (options: ExclusiveUnion<EuiSelectableGroupLabelOption<T>, EuiSelectableLIOption<T>>[], event: EuiSelectableOnChangeEvent, changedOption: ExclusiveUnion<...>) => void | Default value |
Prop onActiveOptionChange# | Description and type Passes back the current active option whenever the user changes the currently (option: (DisambiguateSet<EuiSelectableGroupLabelOption<{}>, EuiSelectableLIOption<{}>> & CommonProps & { ...; } & HTMLAttributes<...>) | (DisambiguateSet<...> & ... 2 more ... & { ...; })) => void | Default value |
Prop singleSelection# | Description and type Sets the single selection policy of boolean | "always" | Default value false |
Prop allowExclusions# | Description and type Allows marking options as boolean | Default value |
Prop isLoading# | Description and type Show an loading indicator while you load and hook up your data boolean | Default value |
Prop height# | Description and type Sets the max height in pixels or pass number | "full" | Default value |
Prop listProps# | Description and type See #EuiSelectableOptionsList EuiSelectableOptionsListPropsWithDefaults | Default value |
Prop renderOption# | Description and type Custom render function for each option. (option: ExclusiveUnion<EuiSelectableGroupLabelOption<T>, EuiSelectableLIOption<T>>, searchValue: string) => ReactNode | Default value |
Prop loadingMessage# | Description and type Customize the loading message. Pass a string to simply change the text, string | ReactElement | Default value |
Prop noMatchesMessage# | Description and type Customize the no matches message. Pass a string to simply change the text, string | ReactElement | Default value |
Prop emptyMessage# | Description and type Customize the empty message. Pass a string to simply change the text, string | ReactElement | Default value |
Prop errorMessage# | Description and type Add an error message.
string | ReactElement | Default value |
Prop isPreFiltered# | Description and type Control whether or not options get filtered internally (i.e., whether filtering is Additionally allows passing a configuration object which enables turning off boolean | { highlightSearch?: boolean; } | Default value false |
Prop selectableScreenReaderText# | Description and type Optional screen reader instructions to announce upon focus/interaction. This text is read out string | Default value |
Prop optionMatcher# | Description and type Optional custom option matcher function EuiSelectableOptionMatcher<T> | Default value createPartialStringEqualityOptionMatcher() |
EuiSelectableMessage
Prop | Description and type | Default value |
|---|---|---|
Prop className# | Description and type Type: string | Default value |
Prop aria-label# | Description and type Defines a string value that labels the current element. string | Default value |
Prop data-test-subj# | Description and type Type: string | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop bordered# | Description and type Match this to the boolean | Default value false |