Combobox Field

Combo box is a searchable multi select or single select field with the ability to nest options into sub-menus.

Overview

Combobox fields are a searchable, multi or single select popover, with the ability to nest options into groups and sub groups.

When to use

When a presenting a list with more than 20 options, so that options can be searched through in an easy manner.
When a user is familiar with the options so searching enables a quicker interaction.
When multi select is required.
When options need to be nested into groups or sub groups.

When not to use

For a small number of options - use Radio or Checkbox instead
For a flat list of options that do not need to be searchable - use Select Field instead

Anatomy

Label
Placeholder text
Removable chip (multi-select only)
List options popover
Group label
List options

Basic usage


Edit live code
<ComboboxField
  id="fruits"
  label="Select your favourite fruits"
  multiple
  options={[
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Cherry', value: 'cherry' },
    { label: 'Mango', value: 'mango' },
    { label: 'Orange', value: 'orange' },
  ]}
/><ComboboxField
  id="fruits"
  label="Select your favourite fruits"
  multiple
  options={[
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Cherry', value: 'cherry' },
    { label: 'Mango', value: 'mango' },
    { label: 'Orange', value: 'orange' },
  ]}
/>

Variants

Flat list - Multi-select

When options have no nested structure, pass a flat list of checkbox options.


Edit live code
<ComboboxField
  id="energy"
  label="Select energy sources"
  multiple
  options={[
    { label: 'Solar', value: 'solar' },
    { label: 'Wind', value: 'wind' },
    { label: 'Hydro', value: 'hydro' },
    { label: 'Geothermal', value: 'geothermal' },
  ]}
/><ComboboxField
  id="energy"
  label="Select energy sources"
  multiple
  options={[
    { label: 'Solar', value: 'solar' },
    { label: 'Wind', value: 'wind' },
    { label: 'Hydro', value: 'hydro' },
    { label: 'Geothermal', value: 'geothermal' },
  ]}
/>

Flat list - Single-select

When options have no nested structure, pass a flat list of options.


Edit live code
<ComboboxField
  id="favourite-fruit"
  label="Select your favourite fruit"
  options={[
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Cherry', value: 'cherry' },
    { label: 'Mango', value: 'mango' },
    { label: 'Orange', value: 'orange' },
  ]}
/><ComboboxField
  id="favourite-fruit"
  label="Select your favourite fruit"
  options={[
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Cherry', value: 'cherry' },
    { label: 'Mango', value: 'mango' },
    { label: 'Orange', value: 'orange' },
  ]}
/>

Grouped options - Multi-select

Pass nested options arrays to organise items under collapsible group headers. Groups can be nested up to two levels deep.


Edit live code
<ComboboxField
  id="energy-grouped"
  label="Select energy sources"
  multiple
  options={[
    {
      label: 'Electricity',
      value: 'electricity',
      options: [
        { label: 'Solar', value: 'solar' },
        { label: 'Wind', value: 'wind' },
        { label: 'Hydro', value: 'hydro' },
      ],
    },
    {
      label: 'Gas',
      value: 'gas',
      options: [
        { label: 'Biomethane', value: 'biomethane' },
      ],
    },
  ]}
/><ComboboxField
  id="energy-grouped"
  label="Select energy sources"
  multiple
  options={[
    {
      label: 'Electricity',
      value: 'electricity',
      options: [
        { label: 'Solar', value: 'solar' },
        { label: 'Wind', value: 'wind' },
        { label: 'Hydro', value: 'hydro' },
      ],
    },
    {
      label: 'Gas',
      value: 'gas',
      options: [
        { label: 'Biomethane', value: 'biomethane' },
      ],
    },
  ]}
/>

Grouped options - Single-select

Pass nested options arrays to organise items under collapsible group headers. Groups can be nested up to two levels deep.


Edit live code
<ComboboxField
  id="energy-grouped-single"
  label="Select your main energy source"
  options={[
    {
      label: 'Electricity',
      value: 'electricity',
      options: [
        { label: 'Solar', value: 'solar' },
        { label: 'Wind', value: 'wind' },
        { label: 'Hydro', value: 'hydro' },
      ],
    },
    {
      label: 'Gas',
      value: 'gas',
      options: [
        { label: 'Biomethane', value: 'biomethane' },
      ],
    },
  ]}
/><ComboboxField
  id="energy-grouped-single"
  label="Select your main energy source"
  options={[
    {
      label: 'Electricity',
      value: 'electricity',
      options: [
        { label: 'Solar', value: 'solar' },
        { label: 'Wind', value: 'wind' },
        { label: 'Hydro', value: 'hydro' },
      ],
    },
    {
      label: 'Gas',
      value: 'gas',
      options: [
        { label: 'Biomethane', value: 'biomethane' },
      ],
    },
  ]}
/>

Features

Default interaction

When a user interacts with the field the popover opens by default displaying the groups and/or options.

The groups can be opened by clicking on them or via keyboard interaction.

The options can then be selected by clicking on them or via keyboard interaction.

Search

As soon as a user types into the field, the popover filters to show only matching options. Both selectable items and group headers are included in the search.

Search result	Behaviour
Group labels that match search term	Group displayed open with all children visible
List options that match search term	Group label displayed open with matching list option visible. Other list options in group are hidden.
No results	“No results found” message shown in popover

After an item is selected, the search text clears and the popover returns to its unfiltered state.

Chip selection (multi-select only)

When an item is selected it appears as a Removable Chip inside the input field. Chips wrap onto new lines if they exceed the available width, and the input grows vertically to accommodate them. Long chip labels are truncated with an ellipsis; the full label is shown in a tooltip on hover or focus.

Chips are ordered with the most recently selected item to the right. To deselect an item, click the remove button on the chip, or use keyboard controls.

Accessibility

Keyboard interaction

Location	Key	Action
Text input	Tab	Focus the field; opens the dropdown
Text input	Arrow down	Move focus to the first item in the dropdown
Text input	Arrow left (caret at start)	Move focus to the rightmost chip
Text input	Backspace (caret at start)	Remove the rightmost chip
Chip	Arrow left	Move focus to the previous chip
Chip	Arrow right	Move focus to the next chip (or back to the text input)
Chip	Backspace, Enter, Delete	Remove the focused chip
Dropdown item	Arrow up / Arrow down	Navigate between visible items
Dropdown group header	Enter	Toggle the group open or closed
Dropdown selectable item	Enter	Select or deselect the item

Screen readers

The field is announced to screen readers as a combobox, this is a browser default behaviour inline with W3C guidelines (opens in new window) . When the popover opens, the screen reader announces the field label and that the user can type to narrow the options.

Group item titles are read out with the amount of items selected within that group.

Removable chip screen reader behaviour can be found here.

Content

Label

The field label should describe the category of items being selected, not the action of selecting them.

Hint text

Use hint text to give specific context to the fields requirement.

Placeholder text

Never use placeholder text as a substitute for a label or hint, it disappears on interaction and is inaccessible

Group headers

Avoid creating a group for a single item.
Avoid generic group names like "Other" or "Miscellaneous" unless absolutely necessary.

Selectable option labels

Always use sentence case for option labels.
Avoid repeating the group name in child option labels.
Avoid option labels longer than 5–6 words

Autocomplete

Browser autofill on this field's textbox is controlled by a transitional theme property. Learn how to enable it in your app.

Properties

Name	Values	Default
id (required)Unique identifier for the field	String
label (required)Visible label for the field	String
options (required)Array of selectable options. Each option has a label, value, and optional nested options array for grouping.	Option[]
multipleDetermines whether multiple options can be selected. Defaults to single-select.	Boolean	false
onValueChangeCallback fired when the selection changes. Receives an array when multiple is true, or a single value (or null) when multiple is false.	(newValue: string[]) => void(newValue: string \| null) => void
valueControlled selected value(s). Array when multiple is true, string or null when multiple is false.	string[]string \| null
defaultValueInitial selected value(s) for uncontrolled usage. Array when multiple is true, string when multiple is false.	string[]string
name	String
optionalDisplays an optional indicator on the label	Boolean	false
hintHint text displayed below the label	ReactNode
errorError message displayed below the field	ReactNode
fullWidth	alwaysneversmall	small
autoCompleteWhen the disableAutocomplete theme config flag is enabled (see the Theme guide), autocomplete="off" is set on the underlying textbox and is not overridable — it competes with the combobox's own listbox, per the ARIA APG combobox pattern.	String