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.
Selected options are based on the checked = on property
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' being 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 individual 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.
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 contents and removes all scrolling.
Therefore, we recommend having a large enough container to accommodate all options. You can also remove truncation
by setting textWrap="wrap" when virtualization is off.
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.