SearchAutocomplete

A search input with an accessible results dropdown.

Usage#

import { SearchAutocomplete, SearchAutocompleteItem } from '@backstage/ui';

<SearchAutocomplete
  inputValue={inputValue}
  onInputChange={setInputValue}
>
  {items.map(item => (
    <SearchAutocompleteItem key={item.id} id={item.id} textValue={item.name}>
      {item.name}
    </SearchAutocompleteItem>
  ))}
</SearchAutocomplete>

API reference#

SearchAutocomplete#

Prop	Type	Default	Description
aria-label	string	-	Accessible label for the search input.
aria-labelledby	string	-	ID of the element that labels the search input.
inputValue	string	-	The current input value (controlled).
onInputChange	(value: string) => void	-	Handler called when the input value changes.
placeholder	string	Search	Placeholder text shown when the input is empty. Also used as the accessible label when neither aria-label nor aria-labelledby is provided.
size	smallmedium	small	Visual size of the input. Use small for inline or dense layouts, medium for standalone fields.
isLoading	boolean	false	Whether results are currently loading. Dims existing results and announces loading state to screen readers.
popoverWidth	string	-	Width of the results popover. Accepts any CSS width value. Matches the input width when not set.
popoverPlacement	bottom startbottom endtop starttop end	bottom start	Placement of the results popover relative to the input.
defaultOpen	boolean	false	Whether the results popover is open by default.
children	ReactNode	-	The result items to render inside the autocomplete.
className	string	-	Additional CSS class name for custom styling.
style	CSSProperties	-	Inline CSS styles object.

Inherits all React Aria Autocomplete props.

SearchAutocompleteItem#

Individual result item within the autocomplete list.

Prop	Type	Default	Description
id	string	-	Unique identifier for the item.
textValue	string	-	Plain text value used for keyboard navigation and accessibility.
onAction	() => void	-	Handler called when the item is selected.
children	ReactNode	-	Content to render inside the item.
className	string	-	Additional CSS class name for custom styling.

Examples#

With rich content#

Here's a view when items include a title and description.

const fruits = [
  { id: 'apple', name: 'Apple', description: 'A round fruit' },
  { id: 'banana', name: 'Banana', description: 'A yellow curved fruit' },
  { id: 'cherry', name: 'Cherry', description: 'A small red stone fruit' },
];

function Example() {
  const [inputValue, setInputValue] = useState('');

  const filtered = fruits.filter(fruit =>
    fruit.name.toLowerCase().includes(inputValue.toLowerCase()),
  );

  return (
    <SearchAutocomplete
      placeholder="Search fruits..."
      inputValue={inputValue}
      onInputChange={setInputValue}
    >
      {filtered.map(fruit => (
        <SearchAutocompleteItem
          key={fruit.id}
          id={fruit.id}
          textValue={fruit.name}
        >
          <Text weight="bold">{fruit.name}</Text>
          <Text variant="body-small" color="secondary">
            {fruit.description}
          </Text>
        </SearchAutocompleteItem>
      ))}
    </SearchAutocomplete>
  );
}

In header#

Use popoverWidth to control the dropdown width when placed in constrained layouts like PluginHeader.

Title

<PluginHeader
  title="Title"
  customActions={
    <>
      <SearchAutocomplete
        size="small"
        inputValue={inputValue}
        onInputChange={setInputValue}
        popoverWidth="400px"
      >
        {filtered.map(fruit => (
          <SearchAutocompleteItem
            key={fruit.id}
            id={fruit.id}
            textValue={fruit.name}
          >
            {fruit.name}
          </SearchAutocompleteItem>
        ))}
      </SearchAutocomplete>
    </>
  }
/>

With selection#

Use onAction on items to handle selection and reset the input.

Last selected: none

function Example() {
  const [inputValue, setInputValue] = useState('');
  const [selected, setSelected] = useState<string | null>(null);

  const filtered = fruits.filter(fruit =>
    fruit.name.toLowerCase().includes(inputValue.toLowerCase()),
  );

  return (
    <Flex direction="column" gap="4">
      <SearchAutocomplete
        placeholder="Search fruits..."
        inputValue={inputValue}
        onInputChange={setInputValue}
      >
        {filtered.map(fruit => (
          <SearchAutocompleteItem
            key={fruit.id}
            id={fruit.id}
            textValue={fruit.name}
            onAction={() => {
              setSelected(fruit.name);
              setInputValue('');
            }}
          >
            {fruit.name}
          </SearchAutocompleteItem>
        ))}
      </SearchAutocomplete>
      <Text>Last selected: {selected ?? 'none'}</Text>
    </Flex>
  );
}

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-SearchAutocomplete
bui-SearchAutocompleteSearchField
bui-SearchAutocompleteInput
bui-SearchAutocompleteClear
bui-SearchAutocompletePopover
bui-SearchAutocompleteInner
bui-SearchAutocompleteListBox
bui-SearchAutocompleteLoadingState
bui-SearchAutocompleteEmptyState

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-SearchAutocompleteItem
bui-SearchAutocompleteItemContent

Changelog#

Version 0.18.0#

Breaking Changes

SearchAutocompleteItem Breaking Updated BUI links to use the hosting application's client-side router, including relative destinations and the application's configured router base path, while preserving native browser navigation where required.

Anchor-based components no longer accept the React Aria render prop. BUI now owns the underlying anchor so routing behavior remains consistent across application and plugin package versions.

ListRow, Tag, and table Row now retain client-side navigation when application and plugin packages load separate React Aria copies. Their existing modifier-key, target, download, and link-metadata behavior is unchanged. #35299

Migration Guide:

Remove render props from ButtonLink, ComboboxItem, Link, MenuItem, MenuListBoxItem, SearchAutocompleteItem, SelectItem, and Tab. BUI now selects and renders the appropriate anchor or router link automatically.

Version 0.14.0#

Changes

SearchAutocomplete Made SearchAutocomplete background-aware. The input now adapts its background color based on its parent container's background level. #33437
SearchAutocompleteItem Fixed relative href resolution for BUI link components. Relative paths like ../other are now correctly turned into absolute paths before reaching the React Aria layer, ensuring client-side navigation goes to the right place. #33597

Version 0.13.0#

Changes

SearchAutocomplete SearchAutocompleteItem Added SearchAutocomplete and SearchAutocompleteItem components for building accessible search-with-results patterns. Built on React Aria's Autocomplete with keyboard navigation and screen reader support. Designed for async/external search results with a configurable popover width. #33340