Combobox

Import#

import { Combobox } from '@volue/wave-react';

// you may also access Combobox context via hook:
// import { useComboboxContext } from '@volue/wave-react';

Combobox is a compound component that consists of multiple parts:

• ​
  Combobox: The wrapper that contains all the parts of a combobox and provides context for its children.
• ​
  Combobox.TextInput: The input that allows users to filter the list of items or type the value they want. It is also the trigger for combobox listbox.
• ​
  Combobox.Content: A wrapper for the content to be rendered when the combobox menu is open. It positions itself by aligning over Combobox.TextInput.
• ​
  Combobox.Clear: The button that clears the value of combobox.
• ​
  Combobox.Item: A container for combobox's item of choice.
• ​
  Combobox.ItemText: A wrapper around textual part of Combobox.Item.
• ​
  Combobox.ItemIndicator: A visual cue in form of an icon that is displayed when the item is selected.
• ​
  Combobox.NoValueFound: The wrapper for providing content to display when there are no matching item(s) in the list.

Examples#

Basic#

Combobox displays a list of items for the user to pick from. By default Combobox.TextInput acts as a typeahead search that matches relevant item and reflects the currently selected value. Printable characters will expand the items dropdown and the first item that matches the query will be visually highlighted (based on the order of the items).

With default value#

An initial, uncontrolled value can be provided using the defaultValue prop. The item corresponding with the value will be highlighted on the list.

Controlled value#

You can easily make the Combobox controlled, by passing your own state to value prop. onValueChange handler is called when the selected value changes, allowing you to sync state.

Controlled text value#

In addition to controlling value of the combobox you can also control value of the Combobox.TextInput with textValue prop and onTextValueChange handler.

Autocomplete mode#

Set autocomplete prop to list, to activate autocomplete behavior known as list autocomplete. If the user types one or more characters in the Combobox.TextInput, only items that are relavant for the provided query are displayed. As the user types more text into the input field, the displayed list of matching items is updated.

Autocomplete filtering#

Combobox provides 2 built-in filtering mechanisms based on substring matches with locale sensitive matching support.

• ​
  startsWith (default) shows items that starts with the input value.
• ​
  contains shows items that contains the input value.

Use defaultFilter property to select the filtering strategy that suits your specific use case.

With a clear button#

Use Combobox.Clear component to render a button that clears the selection of the combobox. Focus will automatically move back to the Combobox.TextInput after the value is cleared.

Custom value#

By default, the value must be chosen from a predefined set of values. Use allowsCustomValue prop to indicate that text value doesn't have to match one of items value, and can be accepted by the combobox.

After typing, if the user presses Enter key or clicks out of the combobox without choosing a value from the list, the typed string becomes the value of the combobox.

Disabled#

Combobox can use isDisabled prop to prevent user from interacting, but also single items can be disabled to limit user's choice.

With Form Field#

Use Form Field component to enhance Combobox with: an accessible label, an optional helper text, a feedback message or to show required indicator.

It is recommended to wrap comboboxes with Form Field to create a consistent set of accessible form fields.

Sizes#

Combobox comes in two size variants: medium and small, with the medium size used by default. All sizes are aligned with sizes of other related components like Text Input.

Customized appearance#

Combobox.TextInput and Combobox.Item can be decorated with supporting icons or elements using startElement and endElement props.

Active indicators#

When item inside the Combobox is selected its text content is highligted in bold. For additional emphasis you may include Combobox.ItemIndicator to add a visual indicator rendered when the item is selected.

HTML Form integration#

When used in the context of an HTML form, Combobox automatically renders hidden input element that is kept in sync with the selected value.

You just need to provide name property that will be used when submitting the form.

Accessibility features#

• ​

  Exposed to assistive technology as a combobox using the WAI ARIA Combobox design pattern​.

• ​

  Provides deep keyboard interactions.

API Reference#

Combobox#

Combobox.TextInput#

Combobox.Content#

Combobox.Clear#

Combobox.Item#

Combobox.ItemText#

Combobox.ItemIndicator#

Combobox.NoValueFound#