ComboBox

A text-field that allows the user to select values from a provided items array.

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.

Variant
Size
The selected theme does not has any options for "variant" and "size".
PropertyTypeDescription
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.

currentValue: ""

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.

When textValue is required

Use 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;
Whether the ComboBox allows a non-item matching input value to be set.
allowsEmptyCollection?
boolean;
Whether the combo box allows the menu to be open when the collection is empty.
aria-describedby?
string;
Identifies the element (or elements) that describes the object.
aria-details?
string;
Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-label?
string;
Defines a string value that labels the current element.
aria-labelledby?
string;
Identifies the element (or elements) that labels the current element.
autoFocus?
boolean;
Whether the element should receive focus on render.
children?
ReactNode | ((item: any) => ReactNode);
ReactNode or function to render the list of items.
defaultFilter?
(textValue: string, inputValue: string) => boolean;
The filter function used to determine if a option should be included in the combo box list.
defaultItems?
Iterable<any>;
The list of ComboBox items (uncontrolled).
defaultSelectedKey?
Key;
The initial selected key in the collection (uncontrolled).
defaultValue?
string;
The value of the input (uncontrolled).
description?
ReactNode;
A helpful text.
disabled?
boolean;
If true, the input is disabled.
Defaults to: 
"false"
disabledKeys?
Iterable<Key>;
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
error?
boolean;
If true, the field is considered invalid and if set the errorMessage is shown instead of the description.
Defaults to: 
"false"
errorMessage?
ReactNode | ((v: ValidationResult) => ReactNode);
An error message.
formValue?
"text" | "key";
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.
Defaults to: 
'key'
id?
string;
The element's unique identifier. See MDN.
items?
Iterable<any>;
The list of ComboBox items (controlled).
label?
ReactNode;
Specifies the label of the field.
menuTrigger?
MenuTriggerAction;
The interaction required to display the ComboBox menu.
Defaults to: 
'input'
name?
string;
The name of the input element, used when submitting an HTML form. See MDN.
onBlur?
(e: FocusEvent<HTMLInputElement, Element>) => void;
Handler that is called when the element loses focus.
onChange?
(value: string) => void;
Called when the input value changes.
onFocus?
(e: FocusEvent<HTMLInputElement, Element>) => void;
Handler that is called when the element receives focus.
onFocusChange?
(isFocused: boolean) => void;
Handler that is called when the element's focus status changes.
onKeyDown?
(e: KeyboardEvent) => void;
Handler that is called when a key is pressed.
onKeyUp?
(e: KeyboardEvent) => void;
Handler that is called when a key is released.
onOpenChange?
(isOpen: boolean, menuTrigger?: MenuTriggerAction) => void;
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.
onSelectionChange?
(key: Key | null) => void;
Handler that is called when the selection changes.
placeholder?
string;
Set the placeholder for the select.
readOnly?
boolean;
If true, the input is readOnly.
Defaults to: 
"false"
ref?
Ref<HTMLInputElement>;
Allows getting a ref to the component instance. Once the component unmounts, React will set 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;
If true, the input is required.
Defaults to: 
"false"
selectedKey?
Key | null;
The currently selected key in the collection (controlled).
shouldFocusWrap?
boolean;
Whether keyboard navigation is circular.
slot?
string | null;
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.
validate?
(value: ComboBoxValidationValue) => true | ValidationError | null;
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.
validationBehavior?
"native" | "aria";
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.
Defaults to: 
'native'
value?
string;
The value of the input (controlled).
width?
WidthProp;
Sets the width of the element. You can see allowed tokens here.

ComboBox.Option

aria-label?
string;
An accessibility label for this item.
children?
ReactNode;
The children of the component
download?
string | boolean;
Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
href?
string;
A URL to link to. See MDN.
hrefLang?
string;
Hints at the human language of the linked URL. SeeMDN.
id?
Key;
The unique id of the item.
isDisabled?
boolean;
Whether the item is disabled.
onAction?
() => void;
Handler that is called when a user performs an action on the item. The exact user event depends on the collection's selectionBehavior prop and the interaction modality.
onHoverChange?
(isHovering: boolean) => void;
Handler that is called when the hover state changes.
onHoverEnd?
(e: HoverEvent) => void;
Handler that is called when a hover interaction ends.
onHoverStart?
(e: HoverEvent) => void;
Handler that is called when a hover interaction starts.
ping?
string;
A space-separated list of URLs to ping when the link is followed. See MDN.
referrerPolicy?
HTMLAttributeReferrerPolicy;
How much of the referrer to send when following the link. See MDN.
rel?
string;
The relationship between the linked resource and the current page. See MDN.
routerOptions?
undefined;
Options for the configured client side router.
target?
HTMLAttributeAnchorTarget;
The target window for the link. See MDN.
textValue?
string;
A string representation of the item's contents, used for features like typeahead.
value?
object;
The object value that this item represents. When using dynamic collections, this is set automatically.

ComboBox.Section

aria-label?
string;
An accessibility label for the section.
children
ReactNode;
Children of the section.
dependencies?
readonly any[]
Values that should invalidate the item cache when using dynamic collections.
header
ReactNode;
Section header to display.
id?
Key;
The unique id of the section.
items?
Iterable<object>;
Item objects in the section.
value?
object;
The object value that this section represents. When using dynamic collections, this is set automatically.
Last update: 2 months ago