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>

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

Escape clears the input when it has a value. After a clear, from the clear button or from Escape, focus is on the input and onClear receives the triggering event.

When you pass value and onClear, onClear must reset value. In every other case, a clear empties the input and fires onChange and onValueChange with an empty value. Escape clears whether or not showClearButton is set.

When the input is empty, Escape is not handled, 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        onClear={() => setQuery("")}
12      />
13      <Text size="small">Query: {query || "(empty)"}</Text>
14    </Flex>
15  );

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 type="search" for semantic HTML
  • 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