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.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.
Custom dropdown content
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.
Tooltips
You can add tooltips to the options by passing toolTipContent. Use toolTipProps to pass additional EuiToolTipProps to the tooltip.
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 group labels 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 ifsingleSelection 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.
Custom option matcher
When searching for options, EuiComboBox uses a partial equality string matcher by default, displaying all options whose labels include the searched string and taking isCaseSensitive prop value into account.
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 EuiComboBoxOptionMatcher and returntrue for options that should be visible for given search string.
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.