ComboBox

The ComboBox component is a fully-featured dropdown Menu that manages state of selected items. If you only require users to select single options that render as plain text, we recommend using the Select component instead.

For more information on how to use the features and props for this component, check out the developer documentation.

The ComboBox component can be configured for one of two modes: single-select and multi-select. If the mode is set to multi-select, you can pass an object for selected props. By doing so, you can control which selected items should render as Selectable badges within the ComboBox input region.

The input region can also be used to filter results within the menu by utilizing the onChange callback function. The rendering of the Menu and its items will depend on the props passed to the ComboBox's menu prop. This component also allows for standard Form field structures such as being set required, disabled, or readOnly, as well as including a label, status, or info.

Single-select

Multi-select

NameTypeDefaultDescription
actionsReactNodeAction Buttons that will render within the input.
autoFocusbooleanAutomatically focuses the input on render.
disabledbooleanDisable the control. The browser defaults to false.
idstringSets DOM id for the control and associates label element via 'for' attribute. If an id is not pass, a random id will be generated for any render.
infoReactNodeIt is recommended to pass a simple string to offer guidance. Text will be styled based on status prop.
labelReactNodePass a string or a fragment with an Icon and string.
labelHiddenbooleanVisually hides the label region.
menuMenuPropsMenu related props. @see MenuProps
mode
'single-select' |'multi-select' 
'single-select' Whether it is single selection or multi selection combobox.
namestringSets html name attribute for the underlying control. Useful for mapping to a data field.
onBlur
(selected: Selected |Selected[]) => void 
Callback fired when the ComboBox looses focus within its containing element. This is not specific to the input element. Note, behavior will be enhanced in an upcoming release and the input will be the only focusable element.
onChange(e: ChangeEvent<HTMLInputElement>) => voidCallback fired when the filtering input value changes.
onClick(e: MouseEvent) => voidFired when user clicks on the Combobox input.
onDropdownButtonClick(open: boolean) => voidFired when the user clicks on the dropdown icon to initiate opening the menu. If you want to offer default menu items without an input value, pass this function. This function can be an appropriate time to fetch menu item data. Remember to set the loading prop to true when when fetching data for an empty list.
onFocus
(selected: Selected |Selected[]) => void 
Callback fired when the ComboBox input gains focus.
placeholderstringPlaceholder text
readOnlybooleanMakes the component non editable and non clickable. The browser defaults to false.
requiredbooleanIndicate if the field is required. The browser defaults to false.
selected
{
  items: Selected | Selected[];
  onNew: undefined | (text: string) => void;
  onRemove: undefined | (id: , index: number) => void;
}
Currently selected option, single for single-select, an array for multi-select.
status
'success' |'warning' |'error' 
Set visual state based on a validation state.
valuestringValue of the combobox filtering input.
visualReactNodeA visual which represents the selected item.