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.
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.
Props
EuiComboBox
Prop | Description and type | Default value |
|---|---|---|
Prop data-test-subj# | Description and type Type: string | Default value |
Prop async# | Description and type Updates the list of options asynchronously boolean | Default value false |
Prop className# | Description and type Type: string | Default value |
Prop compressed# | Description and type When boolean | Default value false |
Prop fullWidth# | Description and type When boolean | Default value false |
Prop id# | Description and type Type: string | Default value |
Prop inputRef# | Description and type Type: RefCallback<HTMLInputElement> | Default value |
Prop isClearable# | Description and type Shows a button that quickly clears any input boolean | Default value true |
Prop isDisabled# | Description and type Disables the input boolean | Default value |
Prop isInvalid# | Description and type Type: boolean | Default value |
Prop isLoading# | Description and type Swaps the dropdown options for a loading spinner boolean | Default value |
Prop noSuggestions# | Description and type Doesn't show the suggestions list/dropdown boolean | Default value |
Prop onBlur# | Description and type Type: FocusEventHandler<HTMLDivElement> | Default value |
Prop onChange# | Description and type Called every time the query in the combo box is parsed (options: EuiComboBoxOptionOption<T>[]) => void | Default value |
Prop onFocus# | Description and type Type: FocusEventHandler<HTMLDivElement> | Default value |
Prop onKeyDown# | Description and type Type: KeyboardEventHandler<HTMLDivElement> | Default value |
Prop onSearchChange# | Description and type Called every time the text query in the search box is parsed (searchValue: string, hasMatchingOptions?: boolean) => void | Default value |
Prop placeholder# | Description and type Sets the placeholder of the input string | Default value |
Prop rowHeight# | Description and type Every option must be the same height and must be explicitly set if using a custom render number | Default value |
Prop singleSelection# | Description and type When boolean | EuiComboBoxSingleSelectionShape | Default value false |
Prop sortMatchesBy# | Description and type Display matching options by: SortMatchesBy | Default value 'none' as const |
Prop isCaseSensitive# | Description and type Whether to match options with case sensitivity. boolean | Default value |
Prop optionMatcher# | Description and type Optional custom option matcher function EuiComboBoxOptionMatcher<T> | Default value createPartialStringEqualityOptionMatcher() |
Prop prepend# | Description and type Creates an input group with element(s) coming before input. It won't show if PrependAppendType | Default value undefined |
Prop append# | Description and type Creates an input group with element(s) coming after input. It won't show if PrependAppendType | Default value undefined |
Prop delimiter# | Description and type A special character to use as a value separator. Typically a comma string | Default value |
Prop autoFocus# | Description and type Specifies that the input should have focus when the component loads boolean | Default value |
Prop aria-label# | Description and type Required when rendering without a visible label from EuiFormRow. string | Default value |
Prop aria-labelledby# | Description and type Reference ID of a text element containing the visible label for the combo box when not string | Default value |
Prop truncationProps# | Description and type By default, EuiComboBox will truncate option labels at the end of Note: when searching, custom truncation props are ignored. The highlighted search Partial<Omit<EuiTextTruncateProps, "text" | "children">> | Default value |
Prop inputPopoverProps# | Description and type Allows customizing the underlying EuiInputPopover component Partial<Omit<EuiInputPopoverProps, "input" | "isOpen" | "closePopover">> | Default value |
Prop css# | Description and type Type: Interpolation<Theme> | Default value |
Prop options# | Description and type Array of EuiComboBoxOptionOption objects. See #EuiComboBoxOptionOption EuiComboBoxOptionOption<T>[] | Default value [] |
Prop customOptionText# | Description and type Creates a custom text option. You can use string | Default value |
Prop onCreateOption# | Description and type Type: (searchValue: string, options: EuiComboBoxOptionOption<T>[]) => boolean | void | Default value |
Prop renderOption# | Description and type Type: (option: EuiComboBoxOptionOption<T>, searchValue: string, OPTION_CONTENT_CLASSNAME: string) => ReactNode | Default value |
Prop selectedOptions# | Description and type Type: EuiComboBoxOptionOption<T>[] | Default value [] |