Combo box

Use a EuiComboBox when the input has so many options that the user needs to be able to search them, the user needs to be able to select multiple options, and/or the user should have the ability to specify a custom value in addition to selecting from a predetermined list. If you're unsure of which selection component to use, see EUI's in-depth guide to selection components for more information.

note

You must add an accessible label to each instance of EuiComboBox

Labels can be created by wrapping the combo box in an EuiFormRow with a label, adding an aria-label prop, or passing a text node ID to the aria-labelledby prop.

Disabled

Set the prop isDisabled to make the combo box disabled.

Case-sensitive matching

Set the prop isCaseSensitive to make the combo box option matching case sensitive.

Virtualized

EuiComboBoxList uses react-window to only render visible options to be super fast no matter how many options there are.

Containers

This example demonstrates how the combo box works within containers. Because this component uses portals, it’s important that it works within other portal-using components.

Pill colors

Useful for visualization or tagging systems. You can also pass a color in your option list. The color can be a hex value (like #000) or any other named color value accepted by the EuiBadge component.

Option rendering

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, to both the dropdown option and selected pill. They will not be included in the searchable content as this only matches against the label property.

While it is best to stick to the option.label, option.append, and option.prepend props, you can pass a custom renderOption function which will pass back the single option option and the searchValue to use for highlighting.

You can use the value prop of the option object to store metadata about the option for use in this callback.

Note: virtualization (above) requires that each option have the same height. Ensure that you render the options so that wrapping text is truncated instead of causing the height of the option to change.

Truncation

By default, EuiComboBox truncates long option text at the end of the string. You can use truncationProps and almost any prop that EuiTextTruncate accepts to configure this behavior. This can be configured at the EuiComboBox level, as well as by each individual option.

Groups

You can group options together. The groups won’t match against the search value.

Single selection

To only allow the user to select a single option, provide the singleSelection prop. You may want to render the selected option as plain text instead of pill form. To do this, pass singleSelection={{ asPlainText: true }}

Single selection with prepended label

append and prepend props only work if singleSelection prop is not set to false to avoid multi-lines that makes combobox height greater than that of append and prepend.

Single selection with custom options

You can allow the user to select a single option and also allow the creation of custom options. To do that, use the singleSelection in conjunction with the onCreateOption prop.

Note: Creating custom options might not be obvious to the user, so provide help text explaining that this option is available. You can also customize the custom option text by passing a text to customOptionText prop.

Disallowing custom options

Leave out the onCreateOption prop to disallow the creation of custom options.

Custom options only, with validation

Alternatively, provide the noSuggestions prop to hide the suggestions list and only allow the creation of custom options.

Async

Use the onSearchChange code to handle searches asynchronously. Use theisLoading prop to let the user know that something async is happening.

With delimiter

Pass a unique character to the delimiter prop to aid in option creation. This is best used when knowing that content may be pasted from elsewhere such as a comma separated list.

Sorting matches

By default, the matched options will keep their original sort order. If you would like to prioritize those options that start with the searched string, pass sortMatchesBy="startsWith"to display those options at the top of the list.

Duplicate labels

In general, it is not recommended to use duplicate labels on the options because the user has no way to distinguish between them. If you need duplicate labels, you will need to add a unique key for each option.

Accessible label with aria-labelledby

Sometimes it’s preferable to label a combobox with a heading or paragraph. You can easily create a unique ID for a text element using the HTML ID generator, then pass your unique ID to the aria-labelledby prop.