Skip to main content
On this page

Combobox Field

A searchable multi-select field for choosing one or more options from a long list.

When to use​

  • When the list has more than around 15 options and users need to search to narrow it down
  • When users need to select multiple items from a large set of options
  • When the list is too long to scan comfortably, making a grouped or searchable dropdown more useful than a static list

When not to use​

  • Five or fewer options - use Radio for single selection or Checkbox for multiple selection. Static controls are easier to scan and require less interaction.
  • Single selection from a short, flat list - use Select Field. It is simpler and more familiar for straightforward choices.
  • All options are short and equally scannable - use Select Field. Search adds friction when users can find the right option by reading the list directly.
  • To indicate that a field is unavailable - the disabled state is not supported. Use Summary List to show values that cannot be edited, or conditionally hide the field if it is not relevant in the current context.

Anatomy​

  1. Label
  2. Hint text (optional)
  3. Search icon
  4. Selected chips
  5. Input
  6. Chevron
  7. Dropdown
  8. Option group (optional)
  9. Option
  10. Error text (optional)

Basic usage​

Loading...
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' },
  ]}
/>

Variants and features​

Option groups​

Options can be grouped under collapsible headings by nesting an options array inside a parent option object. Groups are collapsed by default and expand on click or keyboard activation. When the user types a search query, all matching options become visible regardless of which groups are expanded.

Avoid groups that contain only one option. Groups are only worthwhile when they help users orient themselves within a large list. Give groups concise, specific names rather than catch-all labels like "Other".

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

Controlled and uncontrolled​

ComboboxField can be used as either a controlled or uncontrolled component. Pass value and onValueChange together for controlled usage. Use defaultValue alone for uncontrolled usage where you only need to read the final selection on submit.

Controlled, with value and onValueChange:

Loading...
Edit live code
() => { // ignore - for live code example only.
  const Example = () => {
    const [fruit, setFruit] = useState('banana');

    return (
      <Stack spaceBetween={3}>
        <ComboboxField
          id="favourite-fruit-controlled"
          label="Select your favourite fruit"
          value={fruit}
          onValueChange={setFruit}
          options={[
            { label: 'Apple', value: 'apple' },
            { label: 'Banana', value: 'banana' },
            { label: 'Cherry', value: 'cherry' },
            { label: 'Mango', value: 'mango' },
            { label: 'Orange', value: 'orange' },
          ]}
        />
        <P>Current value: {fruit || 'none'}</P>
      </Stack>
    );
  }

  return <Example />;
}

Uncontrolled, with defaultValue:

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

Common form features​

ComboboxField shares validation, hint text, required/optional marking, and field width behaviour with other form fields. See the forms pattern guide for guidance on these topics.