A dropdown for selecting from predefined options with search support.
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' },
]}
/>| 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. |
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.
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. |
<Select
name="font"
label="Font Family"
description="Choose a font family for your document"
options={[ ... ]}
/><Flex>
<Select
size="small"
label="Font family"
options={[ ... ]}
/>
<Select
size="medium"
label="Font family"
options={[ ... ]}
/>
</Flex><Select
name="font"
label="Font Family"
icon={<RiCloudLine />}
options={[ ... ]}
/><Select
isDisabled
label="Font family"
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' },
]}
/>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
]}
/><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' },
]}
/>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
]}
/>Group options under section headings by passing objects with a title and a
nested options array.
<Select
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' },
],
},
]}
/>Sections are preserved when filtering with searchable.
<Select
name="font"
label="Font Family"
searchable
searchPlaceholder="Search fonts..."
options={[
{
title: 'Serif Fonts',
options: [
{ value: 'times', label: 'Times New Roman' },
{ value: 'georgia', label: 'Georgia' },
],
},
{
title: 'Sans-Serif Fonts',
options: [
{ value: 'arial', label: 'Arial' },
{ value: 'helvetica', label: 'Helvetica' },
],
},
]}
/>Size can change at different breakpoints.
<Select
size={{ initial: 'small', lg: 'medium' }}
label="Font family"
options={[ ... ]}
/>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-Selectbui-SelectPopoveraria-describedby, making them accessible to screen readers. Added a descriptionSlot prop to FieldLabel that uses React Aria's slot mechanism to automatically wire up the connection. #33817Migrated all components from useStyles to useDefinition hook. Exported OwnProps types for each component, enabling better type composition for consumers. #33050
Fixed focus ring styles to use React Aria's [data-focus-visible] data attribute instead of the native CSS :focus-visible pseudo-class. This ensures keyboard focus rings render reliably when focus is managed programmatically by React Aria (e.g. inside a GridList, Menu, or Select). #33358
Fixed scroll overflow in Menu and Select popover content when constrained by viewport height. #33049
Fixed focus-visible outline styles for Menu and Select components. #32983
The Select trigger now automatically adapts its background colour based on the parent background context. #33102
aria-label attributes to SearchField components in Select, MenuAutocomplete, and MenuAutocompleteListbox to fix accessibility warnings. #32337Breaking 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.