ProComponents, templates & AI tooling
HeroUI
27.7k
快速开始
组件
发布说明
迁移

SearchField 搜索框

搜索输入字段，包含清除按钮与搜索图标。

FigmaStorybookReact Aria源代码样式源代码

引入

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

用法

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

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

组件结构

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 允许用户输入并清空搜索关键词。它包含搜索图标，并提供可选的清除按钮以便快速重置。

带说明

输入关键词进行搜索 for products
按姓名、邮箱或用户名搜索
import {Description, Label, SearchField} from "@heroui/react";

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

必填字段

至少需要 3 个字符
import {Description, Label, SearchField} from "@heroui/react";

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

校验

将 isInvalid 与 FieldError 配合使用，以展示校验信息。

搜索内容至少需要 3 个字符
搜索内容包含无效字符
import {FieldError, Label, SearchField} from "@heroui/react";

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

禁用状态

此搜索框已禁用
此搜索框已禁用
import {Description, Label, SearchField} from "@heroui/react";

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

受控

控制值以与其他组件同步，或执行自定义格式化。

当前值： （空）
"use client";

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

带校验

在受控数值的基础上实现自定义校验逻辑。

请输入至少 3 个字符后再搜索
"use client";

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

自定义图标

自定义搜索图标与清除按钮图标。

自定义图标子元素
import {Description, Label, SearchField} from "@heroui/react";

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

全宽

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

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

变体

SearchField 支持两种视觉变体：

  • primary（默认）— 带阴影的标准样式，适用于大多数场景
  • secondary — 低强调、无阴影的变体，适合用在 Surface 组件内
import {Label, SearchField} from "@heroui/react";

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

在 Surface 内

在 Surface 内使用时，请使用 variant="secondary"，以应用适合表面背景的低强调变体。

输入关键词进行搜索
使用筛选条件细化搜索
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">

表单示例

包含校验与提交处理的完整表单集成示例。

请输入至少 3 个字符后再搜索
"use client";

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

键盘快捷键

添加快捷键以快速聚焦搜索字段。

使用键盘快捷键快速聚焦此输入框
按⇧S聚焦搜索框
"use client";

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

自定义渲染函数

"use client";

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

export function CustomRenderFunction() {

样式

传入 Tailwind CSS 类

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>
  );
}

自定义组件类

SearchField 使用可自定义的 CSS 类。你可以覆盖这些类名以匹配自己的设计系统。

@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 类

  • .search-field – 根容器，样式非常克制（flex flex-col gap-1）
  • .search-field__group – 搜索图标、输入框与清除按钮的容器，包含边框与背景样式
  • .search-field__input – 搜索输入字段
  • .search-field__search-icon – 左侧显示的搜索图标
  • .search-field__clear-button – 用于清空搜索字段的按钮
  • .search-field--primary – 带阴影的主变体（默认）
  • .search-field--secondary – 无阴影的次变体，适合用在 surface 上

说明： 子组件（Label、Description、FieldError）拥有各自的 CSS 类与样式。自定义方式请参见对应文档。

交互状态

SearchField 会根据状态自动管理以下 data 属性：

  • Invalid：[data-invalid="true"] 或 [aria-invalid="true"] – 无效时会自动隐藏 description 插槽
  • Disabled：[data-disabled="true"] – 当 isDisabled 为 true 时应用
  • Focus Within：[data-focus-within="true"] – 当输入框聚焦时应用
  • Focus Visible：[data-focus-visible="true"] – 当焦点可见（键盘导航）时应用
  • Hovered：[data-hovered="true"] – 当悬停在整个组合上时应用
  • Empty：[data-empty="true"] – 当字段为空时应用（会隐藏清除按钮）

更多属性可通过渲染 prop 获得（见下方的 SearchFieldRenderProps）。

API 参考

SearchField Props

SearchField 继承 React Aria SearchField 组件的全部 props。

Base Props

Prop类型默认值描述
childrenReact.ReactNode | (values: SearchFieldRenderProps) => React.ReactNode-子组件（Label、Group、Input 等）或渲染函数。
classNamestring | (values: SearchFieldRenderProps) => string-用于样式的 CSS 类，支持渲染 prop。
styleReact.CSSProperties | (values: SearchFieldRenderProps) => React.CSSProperties-行内样式，支持渲染 prop。
fullWidthbooleanfalse搜索字段是否占满容器宽度
idstring-元素的唯一标识符。
variant"primary" | "secondary""primary"组件的视觉变体。primary 为默认带阴影样式。secondary 为低强调、无阴影变体，适合用在 surface 上。
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, SearchFieldRenderProps>-使用自定义渲染函数覆盖默认 DOM 元素。

Value Props

Prop类型默认值描述
valuestring-当前值（受控）。
defaultValuestring-默认值（非受控）。
onChange(value: string) => void-值变化时触发的事件处理函数。

Validation Props

Prop类型默认值描述
isRequiredbooleanfalse提交表单前是否要求用户输入。
isInvalidboolean-当前值是否无效。
validate(value: string) => ValidationError | true | null | undefined-自定义校验函数。
validationBehavior'native' | 'aria''native'使用原生 HTML 表单校验或 ARIA 属性。
validationErrorsstring[]-服务端校验错误。

State Props

Prop类型默认值描述
isDisabledboolean-是否禁用输入。
isReadOnlyboolean-是否可选中但不可修改。

Form Props

Prop类型默认值描述
namestring-input 元素的名称，用于 HTML 表单提交。
autoFocusboolean-元素渲染后是否应获得焦点。

Event Props

Prop类型默认值描述
onSubmit(value: string) => void-用户提交搜索（Enter）时触发的事件处理函数。
onClear() => void-按下清除按钮时触发的事件处理函数。

Accessibility Props

Prop类型默认值描述
aria-labelstring-没有可见标签时的无障碍标签。
aria-labelledbystring-用于标注该字段的元素 ID。
aria-describedbystring-用于描述该字段的元素 ID。
aria-detailsstring-包含更多详情的元素 ID。

Composition Components

SearchField 需要与以下独立组件组合使用，请分别导入并直接使用：

  • SearchField.Group – 搜索图标、输入框与清除按钮的容器
  • SearchField.Input – 搜索输入字段
  • SearchField.SearchIcon – 左侧显示的搜索图标
  • SearchField.ClearButton – 用于清空搜索字段的按钮
  • Label – 字段标签组件（@heroui/react）
  • Description – 辅助说明文本组件（@heroui/react）
  • FieldError – 校验错误信息组件（@heroui/react）

这些组件各自拥有 props API。请直接在 SearchField 内组合使用：

<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 继承 React Aria Group 组件的 props。

Prop类型默认值描述
childrenReact.ReactNode | (values: GroupRenderProps) => React.ReactNode-子组件（SearchIcon、Input、ClearButton）或渲染函数。
classNamestring | (values: GroupRenderProps) => string-用于样式的 CSS 类。

SearchField.Input Props

SearchField.Input 继承 React Aria Input 组件的 props。

Prop类型默认值描述
classNamestring-用于样式的 CSS 类。
variant"primary" | "secondary""primary"输入的视觉变体。primary 为默认带阴影样式。secondary 为低强调、无阴影变体，适合用在 surface 上。
placeholderstring-输入为空时显示的占位符文本。
typestring"search"输入类型（会自动设置为 "search"）。

SearchField.SearchIcon Props

SearchField.SearchIcon 是一个用于渲染搜索图标的自定义组件。

Prop类型默认值描述
childrenReact.ReactNode<IconSearch />自定义图标元素。默认为搜索图标。
classNamestring-用于样式的 CSS 类。

SearchField.ClearButton Props

SearchField.ClearButton 继承 React Aria Button 组件的 props。

Prop类型默认值描述
childrenReact.ReactNode<CloseButton icon />按钮的图标或内容。默认为关闭图标。
classNamestring-用于样式的 CSS 类。
slot"clear""clear"必须设置为 "clear"（会自动设置）。

SearchFieldRenderProps

在 className、style 或 children 上使用渲染 prop 时，可使用以下值：

Prop类型描述
isDisabledboolean字段是否禁用。
isInvalidboolean字段当前是否无效。
isReadOnlyboolean字段是否只读。
isRequiredboolean字段是否必填。
isFocusedboolean字段是否聚焦（已弃用，请使用 isFocusWithin）。
isFocusWithinboolean是否有任意子元素聚焦。
isFocusVisibleboolean是否为可见焦点（键盘导航）。
valuestring当前值。
isEmptyboolean字段是否为空。

ScrollShadow 滚动阴影

通过阴影提示可滚动溢出内容，并根据滚动位置自动检测显示或隐藏。

Select 选择器

Select 展示可折叠的选项列表，并允许用户从中选择一项。

本页目录

引入用法组件结构带说明必填字段校验禁用状态受控带校验自定义图标全宽变体在 Surface 内表单示例键盘快捷键自定义渲染函数样式传入 Tailwind CSS 类自定义组件类CSS 类交互状态API 参考SearchField PropsBase PropsValue PropsValidation PropsState PropsForm PropsEvent PropsAccessibility PropsComposition ComponentsSearchField.Group PropsSearchField.Input PropsSearchField.SearchIcon PropsSearchField.ClearButton PropsSearchFieldRenderProps