Select

A dropdown for selecting from predefined options with search support.

Font Family

Usage#

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

<Select
    name="font"
    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		-	Array of options to display in the dropdown.
selectionMode	singlemultiple	single	Single or multiple selection mode.
value	stringstring[]	-	Controlled selected value. String for single, array for multiple.
defaultValue	stringstring[]	-	Initial value for uncontrolled usage. String for single, array for multiple.
onSelectionChange	(key: Key \| null) => void(keys: Selection) => void	-	Called when selection changes.
label	string	-	Visible label above the select.
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	Select an option	Text shown when no option is selected.
size	smallmedium	small	Visual size of the select field.
icon	ReactNode	-	Icon displayed before the selected value.
searchable	boolean	-	Enables search/filter functionality in the dropdown.
searchPlaceholder	string	Search...	Placeholder text for the search input when searchable is true.
isOpen	boolean	-	Controlled open state. Use with onOpenChange.
defaultOpen	boolean	-	Initial open state for uncontrolled usage.
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 select 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 Select props.

Examples#

Label and description#

<Select
  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>
  <Select
    size="small"
    label="Font family"
    options={[ ... ]}
  />
  <Select
    size="medium"
    label="Font family"
    options={[ ... ]}
  />
</Flex>

Small

Medium

With icon#

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

Font Family

Disabled#

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

Font Family

Disabled options#

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

Select an option

Searchable#

Enable filtering with the searchable prop.

<Select
  name="country"
  label="Country"
  searchable
  searchPlaceholder="Search countries..."
  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

Multiple selection#

<Select
  name="options"
  label="Select multiple options"
  selectionMode="multiple"
  options={[
    { value: 'option1', label: 'Option 1' },
    { value: 'option2', label: 'Option 2' },
    { value: 'option3', label: 'Option 3' },
    { value: 'option4', label: 'Option 4' },
  ]}
/>

Select multiple options

Searchable multiple#

Combine search and multiple selection.

<Select
  name="skills"
  label="Skills"
  searchable
  selectionMode="multiple"
  searchPlaceholder="Filter skills..."
  options={[
    { value: 'react', label: 'React' },
    { value: 'typescript', label: 'TypeScript' },
    { value: 'javascript', label: 'JavaScript' },
    { value: 'python', label: 'Python' },
    // ... more options
  ]}
/>

Skills

Responsive#

Size can change at different breakpoints.

<Select
  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-Select
bui-Select[data-size="small"]
bui-Select[data-size="medium"]
bui-SelectPopover
bui-SelectTrigger
bui-SelectTriggerChevron
bui-SelectValue
bui-SelectList
bui-SelectItem
bui-SelectItemIndicator
bui-SelectItemLabel
bui-SelectSearchWrapper
bui-SelectSearch
bui-SelectSearchClear
bui-SelectNoResults

Changelog#

Version 0.11.0#

Changes

Added missing aria-label attributes to SearchField components in Select, MenuAutocomplete, and MenuAutocompleteListbox to fix accessibility warnings. #32337

Version 0.9.0#

Breaking Changes

Breaking The SelectProps interface now accepts a generic type parameter for selection mode.

Added searchable and multiple selection support to Select component. The component now accepts searchable, selectionMode, and searchPlaceholder props to enable filtering and multi-selection modes. #31649

Migration Guide:

If you're using SelectProps type directly, update from SelectProps to SelectProps<'single' | 'multiple'>. Component usage remains backward compatible.

Changes

Fixed CSS issues in Select component including popover width constraints, focus outline behavior, and overflow handling. #31618