Combobox

Usage#

import { Combobox } from '@backstage/ui';

<Combobox
  name="font"
  label="Font Family"
  options={[
    { id: 'sans', label: 'Sans-serif' },
    { id: 'serif', label: 'Serif' },
    { id: 'mono', label: 'Monospace' },
    { id: 'cursive', label: 'Cursive' },
  ]}
/>

Provide a visible label whenever possible, or use aria-label or aria-labelledby when the field is labeled elsewhere.

Collections#

Combobox accepts one collection source at a time:

• Pass an options array for standard text rows with optional descriptions, icons, or sections.
• Pass items with a child render function for domain objects or custom rows.
• Compose item children directly for a short, fixed collection.
• Pass a useAsyncList result to options or items for asynchronous data and incremental loading.

The prop types prevent mixing collection sources and incompatible search or loading configurations.

Every option or item passed through options or items needs a stable id. Dynamic render functions receive the full source item, and React Aria supplies its identity to the rendered item component. Statically composed items may provide their own id.

Use ComboboxItemText and ComboboxItemProfile for standard rich rows. Use the low-level ComboboxItem for fully custom content, and provide its textValue for filtering and accessibility.

Option sections are supported only in static options arrays.

Search and selection#

Combobox filters loaded items with a client-side contains match by default. Pass search.filter to match against the full option or item. Custom filters require an options or items source; static composition uses the default text-value match. Pass search={{ mode: 'server' }} with a useAsyncList source to forward the input query to the source instead. To control a client query, pass search.inputValue together with search.onInputChange. Use search.defaultInputValue to set an initial uncontrolled query.

Regular collections use item keys for value, defaultValue, and onChange. Direct async server collections use the full option or item instead. This lets the Combobox retain the selected item while the current server results change. Custom async server items require a canonical textValue; plain options use their label.

While the user edits a direct async server Combobox, the selected item remains committed. Leaving the field restores its canonical text and queries the source with that text. With allowsCustomValue, unmatched text remains in the input and no option is selected.

If server data is managed elsewhere, control search.inputValue and search.onInputChange yourself. This manual mode keeps key-based selection. Pass loading to report loading state and optionally load more results. In server mode, direct useAsyncList sources provide their own query and loading state and cannot be combined with these manual props.

API reference#

Inherits all React Aria ComboBox props.

Option types#

The options prop accepts an array containing either of the following shapes. Use id for new code. The deprecated value identity remains supported for static arrays.

Option

OptionSection

ComboboxItem#

Low-level item wrapper for fully custom item content.

Inherits all React Aria ListBoxItem props.

ComboboxItemText#

Preset item with a title, optional description, and optional leading icon.

Inherits all React Aria ListBoxItem props.

ComboboxItemProfile#

Preset item with an avatar and profile name.

Inherits all React Aria ListBoxItem props.

Examples#

Label and description#

<Combobox
  name="font"
  label="Font Family"
  description="Choose a font family for your document"
  options={[ ... ]}
/>

Search#

Pass search.filter to replace the default contains match.

<Combobox
  label="Owner"
  options={ownerOptions}
  search={{
    filter: (option, query) =>
      option.label.toLocaleLowerCase().startsWith(query.toLocaleLowerCase()),
  }}
/>

Custom items#

Use item presets or low-level items for fixed rich rows, or pass domain objects through items with a child render function. Pass dependencies when that render function also depends on values outside each item. Presets include the standard BUI selection indicator. Low-level items own their internal layout and selection treatment; set showSelectionIndicator to use the standard indicator and content layout.

import { Combobox, ComboboxItemProfile } from '@backstage/ui';

<Combobox label="Owner" items={owners}>
  {owner => (
    <ComboboxItemProfile
      name={owner.name}
      src={owner.avatarUrl}
    />
  )}
</Combobox>

Server search and loading#

Import useAsyncList from @backstage/ui and pass its result directly to options or items. The Combobox derives query state, loading state, and incremental loading from the list.

Direct async server collections use the full selected option or item for value, defaultValue, and onChange. Custom items need an id and a canonical textValue; plain options use their label. The selected item remains committed while the user edits the query. Leaving the field restores its canonical text unless allowsCustomValue keeps unmatched text.

import { useState } from 'react';
import { Combobox, ComboboxItemProfile, useAsyncList } from '@backstage/ui';

type Owner = {
  id: string;
  textValue: string;
  name: string;
  avatarUrl?: string;
};

const owners = useAsyncList<Owner>({
  async load({ signal, filterText, cursor }) {
    return fetchOwners({ signal, query: filterText, cursor });
  },
});
const [owner, setOwner] = useState<Owner | null>(null);

<Combobox
  label="Owner"
  items={owners}
  placeholder="Search or select an owner"
  search={{ mode: 'server' }}
  value={owner}
  onChange={setOwner}
>
  {owner => <ComboboxItemProfile name={owner.name} src={owner.avatarUrl} />}
</Combobox>

If data fetching is managed elsewhere, control the server query through search and pass loading with the current state and optional load-more callback. This manual mode keeps the regular key-based selection API.

<Combobox
  label="Owner"
  options={results}
  search={{
    mode: 'server',
    inputValue: query,
    onInputChange: setQuery,
  }}
  loading={{ state: isLoading ? 'filtering' : 'idle', onLoadMore }}
/>

Sizes#

<Flex>
  <Combobox
    size="small"
    label="Font family"
    options={[ ... ]}
  />
  <Combobox
    size="medium"
    label="Font family"
    options={[ ... ]}
  />
</Flex>

With icon#

<Combobox
  name="font"
  label="Font Family"
  icon={<RiCloudLine />}
  options={[ ... ]}
/>

Disabled#

<Combobox
  isDisabled
  label="Font family"
  options={[ ... ]}
/>

Disabled options#

<Combobox
  name="font"
  label="Font Family"
  placeholder="Pick a font"
  disabledKeys={['cursive', 'serif']}
  options={[
    { id: 'sans', label: 'Sans-serif' },
    { id: 'serif', label: 'Serif' },
    { id: 'mono', label: 'Monospace' },
    { id: 'cursive', label: 'Cursive' },
  ]}
/>

Custom values#

Set allowsCustomValue to keep text that does not match an option. Custom text does not create a selected option.

<Combobox
  name="country"
  label="Country"
  allowsCustomValue
  placeholder="Type any country"
  options={[
    { id: 'us', label: 'United States' },
    { id: 'ca', label: 'Canada' },
    { id: 'uk', label: 'United Kingdom' },
    { id: 'fr', label: 'France' },
    { id: 'de', label: 'Germany' },
    // ... more options
  ]}
/>

With sections#

Group options under section headings by passing objects with a title and a nested options array.

<Combobox
  name="font"
  label="Font Family"
  options={[
    {
      title: 'Serif Fonts',
      options: [
        { id: 'times', label: 'Times New Roman' },
        { id: 'georgia', label: 'Georgia' },
        { id: 'garamond', label: 'Garamond' },
      ],
    },
    {
      title: 'Sans-Serif Fonts',
      options: [
        { id: 'arial', label: 'Arial' },
        { id: 'helvetica', label: 'Helvetica' },
        { id: 'verdana', label: 'Verdana' },
      ],
    },
  ]}
/>

Responsive#

Size can change at different breakpoints.

<Combobox
  size={{ initial: 'small', lg: 'medium' }}
  label="Font family"
  options={[ ... ]}
/>

Changelog#

Version 0.16.0#

Breaking Changes

• Breaking Combobox now supports async collections, incremental loading, client and server search, and rich or custom item rendering. Loading placeholders expose .bui-ComboboxLoading and .bui-ComboboxLoadingRow, and stale visible results expose data-stale on .bui-ComboboxList.

  The public ComboboxProps interface is now a union type. #34489

  Migration Guide:

  Required on upgrade:

  Replace interfaces that extend ComboboxProps with type intersections.

  - interface MyComboboxProps extends ComboboxProps {
  -   trackingId: string;
  - }
  + type MyComboboxProps = ComboboxProps & {
  +   trackingId: string;
  + };
  

  Optional migration away from deprecated APIs:

  Prefer id instead of value for plain options. Existing array-valued options using value remain supported as a deprecated compatibility path, but new option content fields and async option sources require id.

  Move input state and custom filtering into the nested search configuration:

  - <Combobox inputValue={query} onInputChange={setQuery} />
  + <Combobox search={{ inputValue: query, onInputChange: setQuery }} />
  

  The existing top-level input state props remain supported as a deprecated compatibility path for plain-array options.

Changes

• Fixed async pagination in Combobox and Select popovers so additional pages load as users scroll instead of loading every page immediately. Combobox now uses .bui-PopoverContent as its scroll container, while all Select variants use the new .bui-SelectResults results container.

  Searchable Select keeps its search field fixed while results scroll. The new public classes .bui-SelectContent and .bui-SelectResults expose this layout for theme customization. #34591

• Fixed Combobox client search crashing when used with plain options. #34590

Version 0.15.0#

Changes

• Added a new Combobox component. It pairs a text input with a filterable dropdown of options and supports single selection, sectioned options, icons, sizes, and custom typed values via allowsCustomValue. #34118