SearchField

Import

import { SearchField } from '@heroui/react';

Usage

Anatomy

import {SearchField, Label, Description, FieldError} from '@heroui/react';

export default () => (
  <SearchField>
    <Label />
    <SearchField.Group>
      <SearchField.SearchIcon />
      <SearchField.Input />
      <SearchField.ClearButton />
    </SearchField.Group>
    <Description />
    <FieldError />
  </SearchField>
)

SearchField allows users to enter and clear a search query. It includes a search icon and an optional clear button for easy reset.

With Description

Required Field

Validation

Use isInvalid together with FieldError to surface validation messages.

Disabled State

Controlled

Control the value to synchronize with other components or perform custom formatting.

With Validation

Implement custom validation logic with controlled values.

Custom Icons

Customize the search icon and clear button icons.

Full Width

Variants

The SearchField component supports two visual variants:

• primary (default) - Standard styling with shadow, suitable for most use cases
• secondary - Lower emphasis variant without shadow, suitable for use in Surface components

In Surface

When used inside a Surface component, use variant="secondary" to apply the lower emphasis variant suitable for surface backgrounds.

Form Example

Complete form integration with validation and submission handling.

With Keyboard Shortcut

Add keyboard shortcuts to quickly focus the search field.

Custom Render Function

Styling

Passing Tailwind CSS classes

import {SearchField, Label} from '@heroui/react';

function CustomSearchField() {
  return (
    <SearchField className="gap-2">
      <Label className="text-sm font-semibold">Search</Label>
      <SearchField.Group className="rounded-xl border-2">
        <SearchField.SearchIcon className="text-blue-500" />
        <SearchField.Input className="text-center font-bold" />
        <SearchField.ClearButton className="text-red-500" />
      </SearchField.Group>
    </SearchField>
  );
}

Customizing the component classes

SearchField uses CSS classes that can be customized. Override the component classes to match your design system.

@layer components {
  .search-field {
    @apply flex flex-col gap-1;
  }

  /* When invalid, the description is hidden automatically */
  .search-field[data-invalid],
  .search-field[aria-invalid] {
    [data-slot="description"] {
      @apply hidden;
    }
  }

  .search-field__group {
    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border;
  }

  .search-field__input {
    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
  }

  .search-field__search-icon {
    @apply text-field-placeholder pointer-events-none shrink-0 ml-3 mr-0 size-4;
  }

  .search-field__clear-button {
    @apply mr-1 shrink-0;
  }
}

CSS Classes

• .search-field – Root container with minimal styling (flex flex-col gap-1)
• .search-field__group – Container for search icon, input, and clear button with border and background styling
• .search-field__input – The search input field
• .search-field__search-icon – The search icon displayed on the left
• .search-field__clear-button – Button to clear the search field
• .search-field--primary – Primary variant with shadow (default)
• .search-field--secondary – Secondary variant without shadow, suitable for use in surfaces

Note: Child components (Label, Description, FieldError) have their own CSS classes and styling. See their respective documentation for customization options.

Interactive States

SearchField automatically manages these data attributes based on its state:

• Invalid: [data-invalid="true"] or [aria-invalid="true"] - Automatically hides the description slot when invalid
• Disabled: [data-disabled="true"] - Applied when isDisabled is true
• Focus Within: [data-focus-within="true"] - Applied when the input is focused
• Focus Visible: [data-focus-visible="true"] - Applied when focus is visible (keyboard navigation)
• Hovered: [data-hovered="true"] - Applied when hovering over the group
• Empty: [data-empty="true"] - Applied when the field is empty (hides clear button)

Additional attributes are available through render props (see SearchFieldRenderProps below).

API Reference

SearchField Props

SearchField inherits all props from React Aria's SearchField component.

Base Props

Value Props

Validation Props

State Props

Form Props

Event Props

Accessibility Props

Composition Components

SearchField works with these separate components that should be imported and used directly:

• SearchField.Group - Container for search icon, input, and clear button
• SearchField.Input - The search input field
• SearchField.SearchIcon - The search icon displayed on the left
• SearchField.ClearButton - Button to clear the search field
• Label - Field label component from @heroui/react
• Description - Helper text component from @heroui/react
• FieldError - Validation error message from @heroui/react

Each of these components has its own props API. Use them directly within SearchField for composition:

<SearchField isRequired isInvalid={hasError} value={value} onChange={setValue}>
  <Label>Search</Label>
  <SearchField.Group>
    <SearchField.SearchIcon />
    <SearchField.Input placeholder="Search..." />
    <SearchField.ClearButton />
  </SearchField.Group>
  <Description>Enter keywords to search</Description>
  <FieldError>Search query is required</FieldError>
</SearchField>

SearchField.Group Props

SearchField.Group inherits props from React Aria's Group component.

SearchField.Input Props

SearchField.Input inherits props from React Aria's Input component.

SearchField.SearchIcon Props

SearchField.SearchIcon is a custom component that renders the search icon.

SearchField.ClearButton Props

SearchField.ClearButton inherits props from React Aria's Button component.

SearchFieldRenderProps

When using render props with className, style, or children, these values are available: