Combobox

A text input paired with a filterable dropdown for selecting or typing a value.

Font Family

Usage#

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

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

API reference#

Prop	Type	Default	Description
options	(Option \| OptionSection)[]	-	Options to display in the dropdown. Pass Option objects directly, or OptionSection objects to render grouped options under section headings.
allowsCustomValue	boolean	false	When true, the typed text is accepted as the value on blur or Enter even if it does not match any option.
value	string	-	Controlled selected value.
defaultValue	string	-	Initial value for uncontrolled usage.
onChange	(value: Key \| null) => void	-	Called when the selected option changes.
inputValue	string	-	Controlled input text.
defaultInputValue	string	-	Initial input text for uncontrolled usage.
onInputChange	(value: string) => void	-	Called when the input text changes.
label	string	-	Visible label above the combobox.
secondaryLabel	string	-	Secondary text shown next to the label. If not provided and isRequired is true, displays Required.
description	string	-	Helper text displayed below the label.
placeholder	string	-	Text shown when the input is empty.
size	smallmedium	small	Visual size of the combobox field.
icon	ReactNode	-	Icon displayed before the input.
onOpenChange	(isOpen: boolean) => void	-	Called when the dropdown opens or closes.
isDisabled	boolean	-	Prevents user interaction when true.
disabledKeys	Iterable<Key>	-	Keys of options that should be disabled.
isRequired	boolean	-	Marks the field as required for form validation.
isInvalid	boolean	-	Displays the combobox in an error state.
name	string	-	Form field name for form submission.
className	string	-	Additional CSS class name for custom styling.
style	CSSProperties	-	Inline CSS styles object.

Inherits all React Aria ComboBox props.

Option types#

The options prop accepts an array containing either of the following shapes.

`Option`

Prop	Type	Default	Description
value	string	-	Unique value for the option.
label	string	-	Display text for the option.
disabled	boolean	-	Whether the option is disabled.

`OptionSection`

Prop	Type	Default	Description
title	string	-	Heading displayed above the grouped options.
options	Option[]	-	Options nested inside the section.

Examples#

Label and description#

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

Font Family

Choose a font family for your document

Sizes#

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

Small

Medium

With icon#

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

Font Family

Disabled#

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

Font Family

Disabled options#

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

Font Family

Custom values#

Allow the user to type a value that is not in the option list by setting allowsCustomValue.

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

Country

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: [
        { value: 'times', label: 'Times New Roman' },
        { value: 'georgia', label: 'Georgia' },
        { value: 'garamond', label: 'Garamond' },
      ],
    },
    {
      title: 'Sans-Serif Fonts',
      options: [
        { value: 'arial', label: 'Arial' },
        { value: 'helvetica', label: 'Helvetica' },
        { value: 'verdana', label: 'Verdana' },
      ],
    },
  ]}
/>

Font Family

Responsive#

Size can change at different breakpoints.

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

Theming#

Our theming system is based on a mix between CSS classes, CSS variables and data attributes. If you want to customise this component, you can use one of these class names below.

bui-Combobox
bui-ComboboxPopover