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.

For more details on which selection component to use, see the Component comparison.

It's not intended for primary navigation

EuiSelectable 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.

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' 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 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.

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.

Testing environment

In a testing environment, virtualization will prevent all options from being rendered to the DOM, which can cause test selectors to fail. You can disable it with listProps.isVirtualized set to false.

When testing EuiSelectable directly, you can pass listProps={{ isVirtualized: false }}.

Alternatively, you can mock EuiSelectable globally:

✄𐘗js code block:
✄𐘗jest.mock("@elastic/eui", () => {
  const { EuiSelectable } = jest.requireActual("@elastic/eui");
  return {
    ...jest.requireActual("@elastic/eui"),
    EuiSelectable: (props: EuiSelectableProps) => {
      return (
        <EuiSelectable
          {...props}
          listProps={{ ...props.listProps, isVirtualized: false }}
        />
      );
    },
  };
});

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

Extends HTMLAttributes


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. @see aria-labelledby. Type: `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) Type: `boolean`	Default value `false`
Prop searchProps#	Description and type Passes props down to the `EuiFieldSearch`. EuiSelectableSearchProps Type: `Partial<EuiSelectableSearchProps<T>>`	Default value
Prop children#	Description and type Function that takes the `list` node and then the `search` node (if `searchable` is applied) Type: `(list: ReactElement<typeof EuiSelectableList \| FunctionComponent<EuiSelectableMessageProps>, string \| JSXElementConstructor<any>>, search: ReactElement<...>) => ReactNode`	Default value
Prop options#	Description and type Array of EuiSelectableOption objects. See EuiSelectableOption Type: `ExclusiveUnion<EuiSelectableGroupLabelOption<T>, EuiSelectableLIOption<T>>[]`	Default value `[]`
Prop onChange#	Description and type Passes back the altered `options` array with selected options having `checked: 'on'`. Also passes back the React click/keyboard event as a second argument, and the option that triggered the onChange event as a third argument. Type: `(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 highlighted option via keyboard navigation or searching. Type: `(option: (DisambiguateSet<EuiSelectableGroupLabelOption<{}>, EuiSelectableLIOption<{}>> & CommonProps & { ...; } & HTMLAttributes<...>) \| (DisambiguateSet<...> & ... 2 more ... & { ...; })) => void`	Default value
Prop singleSelection#	Description and type Sets the single selection policy of `false`: allows multiple selection `true`: only allows one selection `always`: can and must have only one selection Type: `boolean \| "always"`	Default value `false`
Prop allowExclusions#	Description and type Allows marking options as `checked='off'` as well as `'on'` Type: `boolean`	Default value
Prop isLoading#	Description and type Show an loading indicator while you load and hook up your data Type: `boolean`	Default value
Prop height#	Description and type Sets the max height in pixels or pass `full` to allow the whole group to fill the height of its container and allows the list grow as well Type: `number \| "full"`	Default value
Prop listProps#	Description and type See `EuiSelectableOptionsListPropsWithDefaults` Type: `EuiSelectableOptionsListPropsWithDefaults`	Default value
Prop renderOption#	Description and type Custom render function for each option. Returns `(option, searchValue)` Type: `(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, or a node to replace the whole content. Type: `string \| ReactElement`	Default value
Prop noMatchesMessage#	Description and type Customize the no matches message. Pass a string to simply change the text, or a node to replace the whole content. Type: `string \| ReactElement`	Default value
Prop emptyMessage#	Description and type Customize the empty message. Pass a string to simply change the text, or a node to replace the whole content. Type: `string \| ReactElement`	Default value
Prop errorMessage#	Description and type Add an error message. The message will be shown when the value is not `null` or `undefined`. Pass a string to simply change the text, or a node to replace the whole content. `errorMessage={hasErrors ? 'My error message' : null}` Type: `string \| ReactElement`	Default value
Prop isPreFiltered#	Description and type Control whether or not options get filtered internally (i.e., whether filtering is handled by EUI or by you, the consumer). If set to `true`, all passed `options` will be displayed regardless of the user's search input. Additionally allows passing a configuration object which enables turning off search highlighting if needed. Type: `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 after the `EuiSelectable` label and a brief pause, but before the default keyboard instructions for interacting with a selectable are read out. Type: `string`	Default value
Prop optionMatcher#	Description and type Optional custom option matcher function @example const exactEqualityMatcher: EuiSelectableOptionMatcher = ({ option, searchValue }) => { return option.label === searchValue; } Type: `EuiSelectableOptionMatcher<T>`	Default value `createPartialStringEqualityOptionMatcher()`

EuiSelectableMessage

Extends HTMLAttributes


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. @see aria-labelledby. Type: `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 `listProps.bordered` property of your `EuiSelectable` instance Type: `boolean`	Default value `false`