A combobox combines a text input with a listbox, allowing users to filter a list of options to items matching a query.

Combobox follows the WAI-ARIA authoring practices for a combobox.

Import

import { Combobox } from "@fuegokit/react";

Additional styling guides and examples are coming soon. For now, explore the examples at Storybook.

Usage

A combobox consists of a label, input, trigger, and a listbox that contains a collection of items a user can filter.

<Combobox>
  <Combobox.Label>Favorite ice cream</Combobox.Label>
  <Combobox.Input />
  <Combobox.Button>
    <VisuallyHidden>Menu</VisuallyHidden>
    <AkChevronDownIcon />
  </Combobox.Button>
  <Combobox.Popover>
    <Combobox.Listbox>

Styling

To apply styles to the Combobox primitive, use Fuegokit React's themeGet function to access Fuegokit Tokens directly.

Component API

<StyledCombobox>
  <Combobox.Label>Favorite ice cream</Combobox.Label>
  <Box
    className="my-combobox-container"
    sx={{
      display: "flex",
    }}
  >
    <StyledComboboxInput />

CSS

/react/src/Combobox/styles.tsx

const StyledCombobox = styled(Combobox)`
  [slot="description"] {
    font-size: 12px;
  }

  [slot="errorMessage"] {
    font-size: 12px;
    color: var(--ds-text-danger);
  }

Accessibility

Combobox follows the ARIA combobox pattern, with support for items and sections, and it provides slots for label and description elements within each item.

Custom localized announcements are included for option focusing, filtering, and selection using an ARIA live region to ensure announcements are clear and consistent.

Fuegokit React's Combobox is implemented with react-aria. Read more about Combobox's accessibility features, screen reader support, and cross-browser and device support here.

Anatomy

A combobox consists of a label, an input which displays the current value, a list box popup, and an optional button used to toggle the list box popup open state.

Users can type within the input to filter the available options within the list box.

The list box popup may be opened by different interactions specified by the menuTrigger prop provided to Combobox, or by clicking or touching the button.

Combobox also supports optional description and error message elements, which can be used to provide more context about the field, and any validation messages. These are linked with the input via the aria-describedby attribute.

If the combobox does not have a visible label, an aria-label or aria-labelledby prop must be passed instead to identify it to assistive technology.

Combobox

Props

Combobox

Contains all the parts of a Combobox.

Name	Type	Default	Description
defaultFilter	(textValue: string, inputValue: string) => boolean		The filter function used to determine if a option should be included in the combobox list.
shouldFocusWrap	boolean		Whether keyboard navigation is circular.
defaultItems	Iterable<T>	false	The list of Combobox items (uncontrolled).
items	Iterable<T>	-	The list of Combobox items (controlled).
inputValue	string		The value of the Combobox input (controlled).
defaultInputValue	string	false	The default value of the Combobox input (uncontrolled).
allowsCustomValue	boolean	-	Whether the Combobox allows a non-item matching input value to be set.
menuTrigger	MenuTriggerAction	'input'	The interaction required to display the Combobox menu.
disabledKeys	Iterable<Key>	-	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
selectedKey	React.Key \| null	-	The currently selected key in the collection (controlled).
defaultSelectedKey	React.Key	-	The initial selected key in the collection (uncontrolled).
isDisabled	boolean	-	Whether the input is disabled.
isReadOnly	boolean	-	Whether the input can be selected but not changed by the user.
validationState	ValidationState	-	Whether the input should display its "valid" or "invalid" visual styling.
isRequired	boolean	-	Whether user input is required on the input before form submission. Often paired with the necessityIndicator prop to add a visual indicator to the input.
autoFocus	boolean	-	Whether the element should receive focus on render.
children	React.ReactNode \| (values: ComboBoxState<object>) => ReactNode	-	The children of the component. A function may be provided to alter the children based on component state.
className	string \| (values: ComboBoxState<object>) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.
style	React.CSSProperties \| (values: ComboBoxState<object>) => CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Default	Description
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.
onInputChange	(value: string) => void	-	Handler that is called when the ComboBox input value changes.
onSelectionChange	(key: React.Key) => any	-	Handler that is called when the selection changes.
onFocus	(e: FocusEvent<HTMLInputElement>) => void	-	Handler that is called when the element receives focus.
onBlur	(e: FocusEvent<HTMLInputElement>) => void	-	Handler that is called when the element loses 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.

Layout

Name	Type	Default	Description
slot	string	-	A slot name for the component. Slots allow the component to receive props from a parent component.

Accessibility

Name	Type	Default	Description
id	string	-	The element's unique identifier. See MDN.
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.
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.

Combobox.Label

A semantic HTML `<label>` that provides context for the combobox input element.

Name	Type	Default	Description
-	-	-	A `<Combobox.Label>` accepts all props supported by the `<label>` HTML element.

Combobox.Input

A semantic HTML `<input>` element that allows a user to enter plain text with a keyboard.

Name	Type	Default	Description
-	-	-	A <Combobox.Input> accepts all props supported by the <input> HTML element.

Combobox.Button

A semantic HTML `<button>` element that allows a user to perform an action. The `<Combobox.Button>` accepts its contents as `children`. Other props such as `onPress` and `isDisabled` will be set by the Combobox.

Name	Type	Default	Description
isDisabled	boolean	-	Whether the button is disabled.
autoFocus	boolean	-	Whether the element should receive focus on render.
type	'button' \| 'submit' \| 'reset'	'button'	The behavior of the button when used in an HTML form.
children	ReactNode \| (values: ButtonRenderProps) => ReactNode	-	The children of the component. A function may be provided to alter the children based on component state.
className	string \| (values: ButtonRenderProps) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.
style	CSSProperties \| (values: ButtonRenderProps) => CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Default	Description
onPress	(e: PressEvent) => void	-	Handler that is called when the press is released over the target.
onPressStart	(e: PressEvent) => void	-	Handler that is called when a press interaction starts.
onPressChange	(isPressed: boolean) => void	-	Handler that is called when the press state changes.
onPressUp	(e: PressEvent) => void	-	Handler that is called when a press is released over the target, regardless of whether it started on the target or not.
onFocus	(e: FocusEvent<Target>) => void	-	Handler that is called when the element receives focus.
onBlur	(e: FocusEvent<Target>) => void	-	Handler that is called when the element loses 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.

Layout

Name	Type	Default	Description
slot	string	-	A slot name for the component. Slots allow the component to receive props from a parent component.

Accessibility

Name	Type	Default	Description
id	string	-	The element's unique identifier. See MDN.
excludeFromTabOrder	boolean	-	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
aria-expanded	boolean \| 'true' \| 'false'	-	Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
aria-haspopup	boolean \| 'menu' \| 'listbox' \| 'tree' \| 'grid' \| 'dialog' \| 'true' \| 'false'	-	Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
aria-controls	string	-	Identifies the element (or elements) whose contents or presence are controlled by the current element.
aria-pressed	boolean \| 'true' \| 'false' \| 'mixed'	-	Indicates the current "pressed" state of toggle buttons.
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.
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.

Combobox.Popover

The `<Combobox.Popover>` is a container to hold the `<Listbox>` suggestions for a Combobox. By default, it has a placement of `bottom start` within a <Combobox>, but this and other positioning properties can be customized.

Name	Type	Default	Description
triggerRef	RefObject<Element>	-	The ref for the element which the popover positions itself with respect to. When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone.
placement	Placement	'bottom'	The placement of the element with respect to its anchor element.
containerPadding	number	12	The placement padding that should be applied between the element and its surrounding container.
offset	number	0	The additional offset applied along the main axis between the element and its anchor element.
crossOffset	number	0	The additional offset applied along the cross axis between the element and its anchor element.
shouldFlip	boolean	true	Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
isNonModal	boolean	-	Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies. Most popovers should not use this option as it may negatively impact the screen reader experience. Only use with components such as combobox, which are designed to handle this situation carefully.
isKeyboardDismissDisabled	boolean	-	Whether pressing the escape key to close the popover should be disabled. Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided.
arrowSize	number	0	Cross size of the overlay arrow in pixels.
boundaryElement	Element	document.body	Element that that serves as the positioning boundary.
scrollRef	RefObject<Element>	overlayRef	A ref for the scrollable region within the overlay.
shouldUpdatePosition	boolean	true	Whether the overlay should update its position automatically.
arrowBoundaryOffset	number	0	The minimum distance the arrow's edge should be from the edge of the overlay element.
children	ReactNode \| (values: PopoverRenderProps) => ReactNode	-	The children of the component. A function may be provided to alter the children based on component state.
className	string \| (values: PopoverRenderProps) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.
style	CSSProperties \| (values: PopoverRenderProps) => CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Layout

Name	Type	Default	Description
slot	string	-	A slot name for the component. Slots allow the component to receive props from a parent component.

Combobox.Listbox

Within a `<Combobox>`, most listbox props are set automatically. The `<Combobox.Listbox>` component defines the options to display in a Combobox.

Name	Type	Default	Description
selectionBehavior	SelectionBehavior	-	How multiple selection should behave in the collection.
dragAndDropHooks	DragAndDropHooks	-	The drag and drop hooks returned by useDragAndDrop used to enable drag and drop behavior for the ListBox.
renderEmptyState	() => React.ReactNode	-	Provides content to display when there are no items in the list.
offset	number	0	The additional offset applied along the main axis between the element and its anchor element.
label	React.ReactNode	-	An optional visual label for the listbox.
autoFocus	boolean \| FocusStrategy	-	Whether to auto focus the listbox or an option.
shouldFocusWrap	boolean	-	shouldFocusWrap
items	Iterable<T>	-	Item objects in the collection.
arrowSize	number	0	Cross size of the overlay arrow in pixels.
disabledKeys	Iterable<Key>	-	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
scrollRef	React.RefObject<Element>	overlayRef	A ref for the scrollable region within the overlay.
selectionMode	SelectionMode	-	The type of selection that is allowed in the collection.
disallowEmptySelection	boolean	-	Whether the collection allows empty selection.
selectedKeys	'all' \| Iterable<Key>	-	The currently selected keys in the collection (controlled).
className	string \| (values: PopoverRenderProps) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.
defaultSelectedKeys	'all' \| Iterable<Key>	-	The initial selected keys in the collection (uncontrolled).
children	React.ReactNode \| (item: T) => React.ReactElement	-	The contents of the collection.
className	string \| (values: ListBoxRenderProps) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.
style	React.CSSProperties \| (values: ListBoxRenderProps) => React.CSSProperties	-	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Default	Description
onAction	(key: React.Key) => void	-	Handler that is called when a user performs an action on an item. The exact user event depends on the collection's selectionBehavior prop and the interaction modality.
onSelectionChange	(keys: Selection) => any	-	Handler that is called when the selection changes.
onFocus	(e: FocusEvent<Target>) => void	-	Handler that is called when the element receives focus.
onBlur	(e: FocusEvent<Target>) => void	-	Handler that is called when the element loses focus.
onFocusChange	(isFocused: boolean) => void	-	Handler that is called when the element's focus status changes.

Layout

Name	Type	Default	Description
slot	string	-	A slot name for the component. Slots allow the component to receive props from a parent component.

Accessibility

Name	Type	Default	Description
id	string	-	The element's unique identifier. See MDN.
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.
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.

Combobox.Section

A `<Section>` defines the child items for a section within a `<Listbox>`. It may also contain an optional `<Header>` element. If there is no header, then an `aria-label` must be provided to identify the section to assistive technologies.

Name	Type	Default	Description
value	object	-	The object value that this section represents. When using dynamic collections, this is set automatically.
children	ReactNode \| (item: object) => ReactElement	-	Static child items or a function to render children.
items	Iterable<T>	-	Item objects in the section.
className	string	0	The CSS className for the element.
style	CSSProperties	-	The inline style for the element.

Accessibility

Name	Type	Default	Description
id	React.Key	-	The unique id of the section.
aria-label	string	-	Defines a string value that labels the current element.

Combobox.Header

A `<Header>` defines the title for a `<Section>`.

Name	Type	Default	Description
-	-	-	Accepts all DOM attributes

Combobox.Item

An `<Item>` defines a single option within a `<Listbox>`. If the `children` are not plain text, then the `textValue` prop must also be set to a plain text representation, which will be used for autocomplete in the Combobox.

Name	Type	Default	Description
value	object	-	The object value that this section represents. When using dynamic collections, this is set automatically.
title	React.ReactNode	-	Rendered contents of the item if children contains child items.
textValue	string	-	A string representation of the item's contents, used for features like typeahead.
childItems	Iterable<T>	-	A list of child item objects. Used for dynamic collections.
hasChildItems	boolean	-	Whether this item has children, even if not loaded yet.
children	React.ReactNode \| (values: ItemRenderProps) => React.ReactNode	-	The children of the component. A function may be provided to alter the children based on component state.
className	string \| (values: ItemRenderProps) => string	-	The CSS className for the element. A function may be provided to compute the class based on component state.
className	React.CSSProperties \| (values: ItemRenderProps) => React.CSSProperties	-	The CSS className for the element. A function may be provided to compute the class based on component state.

Accessibility

Name	Type	Default	Description
id	React.Key	-	The unique id of the section.
aria-label	string	-	Defines a string value that labels the current element.

Combobox

Import

Usage

Styling

Component API

CSS

Accessibility

Anatomy

Props

Combobox

Combobox.Label

Combobox.Input

Combobox.Button

Combobox.Popover

Combobox.Listbox

Combobox.Section

Combobox.Header

Combobox.Item

See also