ComboBox
The <ComboBox>
component combines a text input with a listbox, allowing users to filter a list of options to items matching a query or adding a new value.
Its purpose is to make interaction with software more intuitive by presenting options in a concise, readable manner instead of requiring users to remember cryptic commands or navigate through complex hierarchies
Appearance
The appearance of a component can be customized using the variant
and size
props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.
Property | Type | Description |
---|---|---|
variant | - | The available variants of this component. |
size | - | The available sizes of this component. |
Usage
Controlled Usage with custom Filter
If you want to listen or act while the user is typing into the ComboBox
field, you can switch to controlled mode by adding an onChange
handler and setting the value
manually.
This is especially helpful if you need to customize the filtering. For example, you may only want to show suggestions when the user has typed at least two characters. Furthermore, you can improve the matching, as shown in the example below. In the demo, the user would not receive a suggestion if they typed "ssp" without the custom filter.
With sections
When related options are present, organizing them into sections enhances clarity and usability. Grouping options provides additional context and helps users navigate choices more easily. This approach reduces complexity and allows for additional guidance when needed, ensuring a more intuitive experience.
This can be achieved by wrapping the options in the <ComboBox.Section>
component. A header is required for each section, which is set using the header
prop. It's important to note that headers are not part of the accessibility tree. As a result, they will not be considered when filtering the option list.
textValue
is requiredUse the textValue
prop when children contain non-text elements (e.g.,
icons, badges, or other decorative components) - this ensures search
functions revieve plain text equivalents, as non-text elements can create
mismatches between visual and semantic content.
Working with asynchronous Data
The ComboBox component supports working with asynchronous data. In the example below, the useAsyncList
hook is used to handle the loading and filtering of data from the server.
Displaying Suggestions
Opening the suggestion popover can be triggered through various interactions. This behavior can be adjusted by the menuTrigger
prop:
input
(default): Open when the user edits the input text.focus
: Open when the user focuses the<ComboBox>
input.manual
: Open when the user presses the trigger button or uses the arrow keys.
The below examples will display the suggestions when the input field is focused.
Props
ComboBox
allowsCustomValue?
boolean;
allowsEmptyCollection?
boolean;
aria-describedby?
string;
aria-details?
string;
aria-label?
string;
aria-labelledby?
string;
autoFocus?
boolean;
children?
ReactNode | ((item: any) => ReactNode);
defaultFilter?
(textValue: string, inputValue: string) => boolean;
defaultItems?
Iterable<any>;
defaultSelectedKey?
Key;
defaultValue?
string;
description?
ReactNode;
disabled?
boolean;
true
, the input is disabled."false"
disabledKeys?
Iterable<Key>;
error?
boolean;
true
, the field is considered invalid and if set the errorMessage
is shown instead of the description
."false"
errorMessage?
ReactNode | ((v: ValidationResult) => ReactNode);
formValue?
"text" | "key";
allowsCustomValue
is true
, this option does not apply and the text is always submitted.'key'
id?
string;
items?
Iterable<any>;
label?
ReactNode;
menuTrigger?
MenuTriggerAction;
'input'
name?
string;
onBlur?
(e: FocusEvent<HTMLInputElement, Element>) => void;
onChange?
(value: string) => void;
onFocus?
(e: FocusEvent<HTMLInputElement, Element>) => void;
onFocusChange?
(isFocused: boolean) => void;
onKeyDown?
(e: KeyboardEvent) => void;
onKeyUp?
(e: KeyboardEvent) => void;
onOpenChange?
(isOpen: boolean, menuTrigger?: MenuTriggerAction) => void;
onSelectionChange?
(key: Key | null) => void;
placeholder?
string;
readOnly?
boolean;
true
, the input is readOnly."false"
ref?
Ref<HTMLInputElement>;
ref.current
to null
(or call the ref with null
if you passed a callback ref).
@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}required?
boolean;
true
, the input is required."false"
selectedKey?
Key | null;
shouldFocusWrap?
boolean;
slot?
string | null;
null
value indicates that the local props completely override all props received from a parent.validate?
(value: ComboBoxValidationValue) => true | ValidationError | null;
validationBehavior="native"
. For realtime validation, use the isInvalid
prop instead.validationBehavior?
"native" | "aria";
'native'
value?
string;
width?
WidthProp;
ComboBox.Option
aria-label?
string;
children?
ReactNode;
download?
string | boolean;
href?
string;
hrefLang?
string;
id?
Key;
isDisabled?
boolean;
onAction?
() => void;
selectionBehavior
prop and the interaction modality.onHoverChange?
(isHovering: boolean) => void;
onHoverEnd?
(e: HoverEvent) => void;
onHoverStart?
(e: HoverEvent) => void;
ping?
string;
referrerPolicy?
HTMLAttributeReferrerPolicy;
rel?
string;
routerOptions?
undefined;
target?
HTMLAttributeAnchorTarget;
textValue?
string;
value?
object;
ComboBox.Section
aria-label?
string;
children
ReactNode;
dependencies?
readonly any[]
header
ReactNode;
id?
Key;
items?
Iterable<object>;
value?
object;