SearchField

A text input for search queries with collapsible and icon support.

Usage#

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

<SearchField />

API reference#

Prop	Type	Default	Description
size	smallmedium	small	Visual size of the input. Use small for inline or dense layouts, medium for standalone fields.
label	string	-	The visible label for the search field.
secondaryLabel	string	-	Secondary label text. Defaults to Required when isRequired is true.
description	string	-	Helper text displayed below the label.
placeholder	string	Search	Placeholder text shown when the field is empty.
icon	ReactNodefalse	-	Icon displayed before the input. Set to false to hide the icon.
startCollapsed	boolean	false	Whether the search field starts in a collapsed state. Expands on focus.
name	string	-	The name of the input for form submission.
value	string	-	The current value (controlled).
defaultValue	string	-	The default value (uncontrolled).
onChange	(value: string) => void	-	Handler called when the value changes.
isDisabled	boolean	-	Whether the search field is disabled.
isReadOnly	boolean	-	Whether the search field is read-only.
isRequired	boolean	-	Whether a value is required before form submission.
isInvalid	boolean	-	Whether the search field is in an invalid state.
className	string	-	Additional CSS class name for custom styling.

Inherits all React Aria SearchField props.

Examples#

Sizes#

<Flex direction="row" gap="4">
  <SearchField aria-label="Search" size="small" />
  <SearchField aria-label="Search" size="medium" />
</Flex>

With description#

Add context below the input with the description prop.

<SearchField
  label="Search"
  description="Enter a search term to filter results"
/>

Enter a search term to filter results

Collapsible#

Use startCollapsed for space-constrained layouts where the field expands on focus.

<Flex direction="row" gap="4">
  <SearchField aria-label="Search" size="small" startCollapsed />
  <SearchField aria-label="Search" size="medium" startCollapsed />
</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-SearchField
bui-SearchField[data-startCollapsed="true"]
bui-SearchField[data-startCollapsed="false"]
bui-SearchField[data-size="small"]
bui-SearchField[data-size="medium"]
bui-SearchFieldClear
bui-SearchFieldInputWrapper
bui-SearchFieldInput
bui-SearchFieldInputIcon