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.Root: The wrapper that holds the data (items), owns the selection state, and provides context to its children.
• ​
  Combobox.TextInput: A text input that filters the list as the user types. It can be the field itself (typeahead) or a search field rendered inside the popup.
• ​
  Combobox.Trigger: A button-style trigger that displays the current selection and opens the popup — pair it with a Combobox.TextInput placed inside Combobox.Content to search.
• ​
  Combobox.CustomTrigger: A headless trigger for building a structurally different trigger element.
• ​
  Combobox.Value: Renders the current selection, useful inside a Combobox.CustomTrigger.
• ​
  Combobox.MultiTrigger: A multi-select field that renders the selected values as removable labels.
• ​
  Combobox.Label: A removable label representing one selected value, rendered by Combobox.MultiTrigger.
• ​
  Combobox.Content: The popup rendered when the combobox is open. It positions itself against the field.
• ​
  Combobox.List: Renders the filtered items via a render function — return one Combobox.Item per item.
• ​
  Combobox.VirtualList: A windowed alternative to Combobox.List for large lists, rendering only the visible rows.
• ​
  Combobox.Item: A selectable option.
• ​
  Combobox.ItemIndicator: A visual cue (a check icon) displayed when the item is selected.
• ​
  Combobox.NoValueFound: The content displayed when no item matches the query.
• ​
  Combobox.Clear: A button that clears the selection.

Examples#

Basic#

Combobox displays a list of items for the user to pick from. By default Combobox.TextInput acts as a typeahead — printable characters open the dropdown and filter the list (a case-insensitive contains match), and the first match is highlighted automatically.

With default value#

An initial, uncontrolled selection can be provided with the defaultValue prop. The matching item is highlighted in the list and its label fills the input.

Controlled value#

Make the Combobox controlled by passing your own state to value and handling onValueChange. Pass null for "no selection".

Controlled input value#

The text typed in the field is exposed separately from the selection. Control it with inputValue and onInputValueChange — useful when you filter the data yourself (set filter={null} and feed already-filtered results to items).

With a clear button#

Render Combobox.Clear to add a button that clears the selection. Focus moves back to Combobox.TextInput after clearing.

Disabled#

Set isDisabled on Combobox.Root to disable the whole field — it can't be focused, typed in, or opened, and its value is excluded from form submission. To disable individual items instead, set isDisabled on Combobox.Item; those items stay visible and filterable but can't be highlighted or selected.

With Form Field#

Use the Form Field component to enhance Combobox with an accessible label, optional helper text, a feedback message, or a required indicator. Wrapping comboboxes with Form Field is recommended for a consistent set of accessible form fields.

Sizes#

Combobox comes in two size variants, medium (default) and small, aligned with the sizes of related components like Text Input. When wrapped in a Form Field, set the size on FormField.Root and on Combobox.Root.

Filtering#

By default the list does a substring (contains) match that is case-, accent-, and punctuation-insensitive, powered by Intl.Collator. String items (and the label of { value, label } objects) filter with no extra setup.

To change the strategy, pass one of Combobox.useFilter()'s matchers — startsWith, contains, or endsWith — to the filter prop. The example below matches only from the start of the word; to match on a different property or several fields at once, see Matching additional fields.

Object items#

Items aren't limited to strings — you can pass objects as value. For a { value, label } shape, the label is automatically used for display and filtering, and the value for form submission. For any other shape, supply itemToStringLabel so typing still filters (and the input fills) by the right text, and itemToStringValue to set the string submitted in a form.

Item content can also be arbitrary markup, such as a two-line cell with a secondary description.

Matching additional fields#

{ value, label } items match on their label out of the box. To match on more, filter's matchers accept a function that turns each item into the text to match. Here it returns the label joined with the ISO code, so typing "pt-pt" finds Portuguese (Portugal) even though its label never contains it.

Custom value#

By default the value must come from the list. Set allowsCustomValue so a typed value doesn't have to match one of the items. After typing, if the user presses Enter or clicks out of the combobox without choosing a value from the list, the typed string becomes the value.

Decorated input and items#

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

Selected indicator#

A selected item's label is highlighted in bold. For additional emphasis you may render Combobox.ItemIndicator inside the item to add a visual indicator shown when the item is selected.

With inline label#

Use startElement on Combobox.TextInput to render an inline label alongside the typed or selected value, keeping the field compact while still communicating its purpose.

Select with search in popup#

You can trigger the combobox from a Combobox.Trigger button that opens a popup whose Combobox.TextInput filters the list.

Omit the trigger's children and it auto-renders the selected item's label (resolved via itemToStringLabel, the item's label field, or the raw string value).

Pass a function as the trigger's children to render custom markup — here the flag alongside the label.

Multiple selection#

Set multiple on Combobox.Root and use Combobox.MultiTrigger instead of a single Combobox.TextInput. Selected values render as removable labels (Combobox.Label), and the composed Combobox.TextInput types alongside them to filter.

Multiple with search in popup#

Because Combobox.TextInput is composed separately, it can live inside the popup instead of inline — Combobox.MultiTrigger then reads as a multi-select trigger showing only the selected labels.

To keep the field compact with many selections, cap the visible labels with maxVisibleItems and collapse the rest into a +N label using renderOverflow.

Virtualised#

Combobox.VirtualList uses virtualisation​ to render only the visible rows of a large list. Set virtualized and items on Combobox.Root, swap Combobox.List for Combobox.VirtualList, and return one Combobox.Item per row.

These patterns all work together. Below is an example of a virtualised multi-select with the search in the popup, like an assignee picker.

Custom trigger#

For a fully custom trigger, use Combobox.CustomTrigger — it's headless, so render any element via as and compose Combobox.Value for the selection.

Within an HTML form#

When used inside an HTML form, Combobox automatically syncs the selected value to a hidden input under the name you provide, so it's available from FormData on submit.

Accessibility features#

• ​

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

• ​

  Provides deep keyboard interactions.

API reference#

Combobox.Root#

Combobox.TextInput#

Combobox.Trigger#

Combobox.CustomTrigger#

Combobox.Value#

Combobox.MultiTrigger#

Combobox.Label#

Combobox.Content#

Combobox.List#

Combobox.VirtualList#

Combobox.Item#

Combobox.ItemIndicator#

Combobox.NoValueFound#

Combobox.Clear#

Combobox.useFilter#

A hook returning collator-based matchers — contains, startsWith, and endsWith — for building a filter predicate. Each takes the item, the query, and an optional itemToString. Pass Intl.Collator options (e.g. { sensitivity: 'accent' }) to override the default case-, accent-, and punctuation-insensitive matching.

const { startsWith } = Combobox.useFilter();

<Combobox.Root items={items} filter={startsWith}>
  {/* … */}
</Combobox.Root>;