Search

A search input component with built-in search icon and optional clear button.

Anatomy

Import and assemble the component:

1import { Search } from "@raystack/apsara";
2

3<Search />

Usage

A text input with the search icon already in place. Set its size, whether it can be cleared, and who owns the value.

Size

Two sizes. large is the default; small fits a toolbar or a table header.

1<Flex direction="column" gap={5} align="center">
2  <Search placeholder="Large size search..." />
3  <Search size="small" placeholder="Small size search..." />
4</Flex>

Leading icon

Pass a node to leadingIcon to replace the search icon, or null to hide it.

1<Flex direction="column" gap={5} align="center">
2  <Search placeholder="Filter..." leadingIcon={<FilterIcon />} />
3  <Search placeholder="No icon..." leadingIcon={null} />
4</Flex>

Clear Button

The Search component can include a clear button that appears when there is input value.

1<Flex direction="column" gap={5} align="center">
2  <Search
3    placeholder="Type to search..."
4    value="Searchable text"
5    showClearButton
6  />
7  <Search placeholder="Basic search..." />
8</Flex>

Clearing

The clear button and Escape clear the input. A clear fires onChange and onValueChange with an empty value, for controlled and uncontrolled inputs. onClear runs after the clear and receives the triggering event. Use it for side effects only.

After the clear button, focus stays on the input. Escape clears the input when it has a value, then removes focus from it. Set clearOnEscape={false} to keep the value, or blurOnEscape={false} to keep focus. Escape clears whether or not showClearButton is set.

When Escape clears a value, Search stops the event. When there is nothing to clear, Escape is not stopped, so it can close an enclosing Dialog, Popover, or Menu.

Controlled value

Use onValueChange to receive only the new query string, or onChange for the full React change event. The Search component forwards both to the underlying Input.

1(function SearchValueChangeExample() {
2  const [query, setQuery] = React.useState("");
3

4  return (
5    <Flex direction="column" gap={5} style={{ width: 400 }}>
6      <Search
7        placeholder="Search items..."
8        value={query}
9        onValueChange={setQuery}
10        showClearButton
11      />
12      <Text size="small">Query: {query || "(empty)"}</Text>
13    </Flex>
14  );

API Reference

Renders a search input field with clear functionality.

Prop

Type

Slots

Every rendered part carries a stable data-slot attribute for styling and testing:

SlotElement
searchThe role="search" container
search-inputThe <input> element itself
search-clearWrapper around the clear button (when showClearButton)
search-clear-buttonThe clear button (when showClearButton)

Accessibility

The Search component is built with accessibility in mind, following ARIA best practices:

  • Container has role="search" to identify it as a search landmark
  • Input has role="searchbox" and enterKeyHint="search". It does not use type="search", because Chrome and Safari clear that input on Escape even when clearOnEscape is false
  • Search icon is marked as decorative with aria-hidden="true"
  • Clear button has appropriate aria-label for screen readers
  • Keyboard navigation support for the clear button
  • Input inherits aria-label from placeholder text

Example with accessibility features:

1<Search
2  placeholder="Search items..."
3  showClearButton
4  value="Searchable text"
5  aria-label="Search items"
6/>

The component supports keyboard navigation:

  • Tab to focus on the search input
  • Tab again to focus on the clear button (when visible)
  • Enter or Space to trigger the clear button
  • Escape to clear the input when it has a value and remove focus from it