SearchFieldNew

Import

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

Usage

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

export function Basic() {
  return (
    <SearchField name="search">

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

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

export function WithDescription() {
  return (
    <div className="flex flex-col gap-4">

Required Field

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

export function Required() {
  return (
    <div className="flex flex-col gap-4">

Validation

Use isInvalid together with FieldError to surface validation messages.

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

export function Validation() {
  return (
    <div className="flex flex-col gap-4">

Disabled State

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

export function Disabled() {
  return (
    <div className="flex flex-col gap-4">

Controlled

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

"use client";

import {Button, Description, Label, SearchField} from "@heroui/react";
import React from "react";

With Validation

Implement custom validation logic with controlled values.

"use client";

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

Custom Icons

Customize the search icon and clear button icons.

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

export function CustomIcons() {
  return (
    <div className="flex flex-col gap-4">

Full Width

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

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-4">

On Surface

When used inside a Surface component, SearchField automatically applies on-surface styling.

import {Description, Label, SearchField, Surface} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6">

Form Example

Complete form integration with validation and submission handling.

"use client";

import {Button, Description, FieldError, Form, Label, SearchField, Spinner} from "@heroui/react";
import React from "react";

With Keyboard Shortcut

Add keyboard shortcuts to quickly focus the search field.

"use client";

import {Description, Kbd, Label, SearchField} from "@heroui/react";
import React from "react";

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__group--on-surface – Applied when used inside a Surface component

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: