Combobox
A combo box allows the user to make a selection from a list of suggested, likely or desired values.
Props
- inputRef?
- isFluid?
- necessityIndicator?
- placeholder?
- prefix?
- size?
- triggerProps?
- style?
- children?
- validationBehavior?
- onSelectionChange?
- selectedKey?
- defaultSelectedKey?
- defaultItems?
- items?
- onOpenChange?
- inputValue?
- defaultInputValue?
- onInputChange?
- allowsCustomValue?
- menuTrigger?
- disabledKeys?
- isDisabled?
- isReadOnly?
- isRequired?
- isInvalid?
- validate?
- autoFocus?
- id?
- name?
- defaultFilter?
- formValue?
- allowsEmptyCollection?
- className?
A ref for the HTML input element.
If true, the select will take all available width.
Whether the required state should be shown as an asterisk or a label, which would display (Optional) on all non required field labels.
The placeholder text when the select is empty.
An icon or text to display at the start of the select trigger.
The size of the select.
The props for the select's trigger.
The inline style for the element. A function may be provided to compute the style based on component state.
The children of the component. A function may be provided to alter the children based on component state.
Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
Handler that is called when the selection changes.
The currently selected key in the collection (controlled).
The initial selected key in the collection (uncontrolled).
The list of ComboBox items (uncontrolled).
The list of ComboBox items (controlled).
Method that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu.
The value of the ComboBox input (controlled).
The default value of the ComboBox input (uncontrolled).
Handler that is called when the ComboBox input value changes.
Whether the ComboBox allows a non-item matching input value to be set.
The interaction required to display the ComboBox menu.
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
Whether the input is disabled.
Whether the input can be selected but not changed by the user.
Whether user input is required on the input before form submission.
Whether the input value is invalid.
A function that returns an error message if a given value is invalid.
Validation errors are displayed to the user when the form is submitted
if validationBehavior="native". For realtime validation, use the isInvalid
prop instead.
Whether the element should receive focus on render.
The element's unique identifier. See MDN.
The name of the input element, used when submitting an HTML form. See MDN.
The filter function used to determine if a option should be included in the combo box list.
Whether the text or key of the selected item is submitted as part of an HTML form.
When allowsCustomValue is true, this option does not apply and the text is always submitted.
Whether the combo box allows the menu to be open when the collection is empty.
The CSS className for the element. A function may be provided to compute the class based on component state.
- onFocus?
- onBlur?
- onFocusChange?
- onKeyDown?
- onKeyUp?
Handler that is called when the element receives focus.
Handler that is called when the element loses focus.
Handler that is called when the element's focus status changes.
Handler that is called when a key is pressed.
Handler that is called when a key is released.
- shouldFocusWrap?
- aria-label?
- aria-labelledby?
- aria-describedby?
- aria-details?
Whether keyboard navigation is circular.
Defines a string value that labels the current element.
Identifies the element (or elements) that labels the current element.
Identifies the element (or elements) that describes the object.
Identifies the element (or elements) that provide a detailed, extended description for the object.
- slot?
A slot name for the component. Slots allow the component to receive props from a parent component.
An explicit null value indicates that the local props completely override all props received from a parent.
Anatomy
Header
The Header component represents a header within a Hopper container.
Section
The Section component represents a section within a Hopper container.
Composed Components
ComboBox
ComboBoxOption
ComboBox Examples
Disabled
A combo box in a disabled state shows that it exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that a field may become available later.
Error
A combo box can be displayed in an error state to indicate that the selection is invalid.
Sizes
A combo box has multiple sizes to choose from. The combo box option also changes size based on the size of the combo box.
Labeling
If a visible label isn't specified, an aria-label must be provided to the combo box for accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using the ID of the labeling element instead.
Icon Prefix
An icon can be displayed at the start of the select trigger.
Text Prefix
A short text can be displayed at the start of the select trigger.
Fluid
A combo box can take the width of its container.
Controlled
A combo box can have a controlled selected value. In this example, it shows how it is possible to deselect an option.
Custom Filtering
A combo box can overridde the default useFilter function from RAC. This can be overridden using the defaultFilter prop, or by using the items prop to control the filtered list. When items is provided rather than defaultItems, combo box does no filtering of its own.
Allow Empty Collection
A combo box can be rendered with an empty collection.
Allow Custom Value
A combo box can allow the user to enter a custom value that does not match the list.
Form
A combo box can be part of a form. To submit the value of a combo box, make sure you specify the name property.
ComboBox Item Examples
Disabled Item
A combo box with a disabled item.
Auto Menu Width
A combo box can have a menu that automatically adjusts its width based on the longest item.
Menu placement
A combo box's menu can have a customized menu placement using the placement prop inside popoverProps.
Section
A combo box can have sections and section headers.
Footer
A combo box can have a footer.
Avatar
A combo box item can contain an avatar.
Count
A combo box item can contain a count using a badge.
Dynamic Lists
Options and sections can be populated from a hierarchial data structure.
If a section has a header, the Collection component can be used to render the child items.
Icons
A combo box item can contain icons.
End Icons
A combo box can contain icons at the end of an option.
Loading
A combo box can have a loading state.
Load on scroll
A combo box can load more items when scrolling within.
Selection indicator
A combo box can have a different selection indicator.
Description
A combo box item can have a description.