Search Field

import { SearchField } from "@/components/ui/search-field";

export default function SearchFieldDemo() {
  return (
    <SearchField
      aria-label="Search"
      className="w-full max-w-xs"
      shortcut="⌘K"
    />
  );
}

Installation

$ pnpm dlx shadcn@latest add @desyne/search-field

The CLI installs dependencies and any other components this one uses.

Usage

tsx

import { SearchField } from "@/components/ui/search-field";

tsx

<SearchField aria-label="Search" onSubmit={(query) => search(query)} />

Use value and onChange to filter as the user types, or onSubmit to run the search when they press Enter. The clear button and Esc reset the value and call onClear.

onSubmit replaces form submission

When onSubmit is set, Enter calls it and does not submit a surrounding <form>. Leave onSubmit off (and give the field a name) when you want Enter to submit the form natively.

When to use

Search Field — a query that filters or searches content elsewhere on the page or site.
Combo Box — the result is picking one option from a list shown under the input.
Command Palette — a global, keyboard-first launcher for navigation and actions.
Text Field — ordinary text entry that isn't a query.

Anatomy

tsx

<SearchField>          {/* root: <div>, owns the query and state attributes */}
  <Label />            {/* from `label` */}
  <FieldGroup>         {/* the visible box */}
    <SearchIcon />     {/* decorative */}
    <FieldInput />     {/* <input type="search"> */}
    <Keyboard />       {/* from `shortcut`, only while empty */}
    <Button />         {/* clear button, only while not empty */}
  </FieldGroup>
  <Description />      {/* from `description` */}
  <FieldError />       {/* shown only while invalid */}
</SearchField>

Part	Renders	Notes
`SearchField`	`<div>`	Root. Carries `data-slot="search-field"`, the `group/field` class and `data-empty` while the query is empty.
`Label`	`<label>`	Rendered when `label` is set.
`FieldGroup`	`<div>`	The visible box, styled by `fieldVariants`.
Search icon	`<svg>`	Decorative (`aria-hidden`).
`FieldInput`	`<input type="search">`	The native input. The browser's own cancel button is hidden in favour of the clear button.
Shortcut	`<kbd>`	Rendered when `shortcut` is set, visible only while the field is empty. It's a hint; you bind the key.
Clear button	`<button>`	Labelled "Clear search", skipped in the tab order, hidden while empty. React Aria wires it through context, so don't place other React Aria buttons inside the field.
`Description`	`<span slot="description">`	Rendered when `description` is set.
`FieldError`	`<span slot="errorMessage">`	Rendered only while invalid.

Examples

Variants

outline (default), filled for toolbars, headers and tinted surfaces, and underlined for minimal layouts.

Outline

Filled

Underlined

import { SearchField } from "@/components/ui/search-field";

export default function SearchFieldVariants() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-5">
      <SearchField
        label="Outline"
        variant="outline"
        placeholder="Search projects…"
      />
      <SearchField
        label="Filled"
        variant="filled"
        placeholder="Search projects…"
      />
      <SearchField
        label="Underlined"
        variant="underlined"
        placeholder="Search projects…"
      />
    </div>
  );
}

Sizes

sm (28px) suits toolbars and table headers, md (32px) is the default, lg (40px) suits hero and landing-page search.

import { SearchField } from "@/components/ui/search-field";

export default function SearchFieldSizes() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      <SearchField aria-label="Search, small" size="sm" shortcut="/" />
      <SearchField aria-label="Search, medium" size="md" shortcut="/" />
      <SearchField aria-label="Search, large" size="lg" shortcut="/" />
    </div>
  );
}

With label and description

Most search fields rely on aria-label, but a visible label helps in forms and filter panels. The default placeholder is "Search…".

Search docs

Press Escape or the × button to clear.

import { SearchField } from "@/components/ui/search-field";

export default function SearchFieldWithLabel() {
  return (
    <SearchField
      className="w-full max-w-xs"
      label="Search docs"
      placeholder="Search components…"
      defaultValue="button"
      description="Press Escape or the × button to clear."
    />
  );
}

Keyboard shortcut

shortcut shows a hint while the field is empty. Binding the key is up to you: listen on window and focus the input. The root doesn't expose the input, so reach it through a wrapper ref.

Press ⌘K (or Ctrl K) anywhere on the page to focus the field.

import { useEffect, useRef } from "react";
import { SearchField } from "@/components/ui/search-field";

export default function SearchFieldShortcut() {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const onKeyDown = (e: KeyboardEvent) => {
      if (e.key.toLowerCase() === "k" && (e.metaKey || e.ctrlKey)) {
        e.preventDefault();
        ref.current?.querySelector("input")?.focus();
      }
    };
    window.addEventListener("keydown", onKeyDown);
    return () => window.removeEventListener("keydown", onKeyDown);
  }, []);

  return (
    <div ref={ref} className="flex w-full max-w-xs flex-col gap-2">
      <SearchField aria-label="Search" shortcut="⌘K" />
      <p className="text-muted-foreground text-xs">
        Press ⌘K (or Ctrl K) anywhere on the page to focus the field.
      </p>
    </div>
  );
}

Submit and clear

onSubmit runs on Enter with the current query, and onClear runs when the clear button or Esc empties the field. Set enterKeyHint="search" to label the enter key on mobile keyboards.

Type a query and press Enter.

import { useState } from "react";
import { SearchField } from "@/components/ui/search-field";

export default function SearchFieldSubmit() {
  const [log, setLog] = useState<string[]>([]);
  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <SearchField
        aria-label="Search orders"
        placeholder="Order number or email…"
        enterKeyHint="search"
        onSubmit={(q) => setLog((l) => [`Searched “${q}”`, ...l].slice(0, 3))}
        onClear={() => setLog((l) => ["Cleared", ...l].slice(0, 3))}
      />
      <ul className="flex flex-col gap-1 text-muted-foreground text-sm">
        {log.length === 0 ? (
          <li>Type a query and press Enter.</li>
        ) : (
          log.map((entry, i) => (
            // biome-ignore lint/suspicious/noArrayIndexKey: short event log
            <li key={i}>{entry}</li>
          ))
        )}
      </ul>
    </div>
  );
}

Control the value with value and onChange to filter a list as the user types. React Aria's useFilter gives you locale-aware contains, startsWith and endsWith matchers that ignore case and accents with sensitivity: "base". Announce the result count with an aria-live region.

17 of 17 components

Button
Calendar
Checkbox
Combo Box
Date Picker
Dialog
Menu
Number Field
Popover
Radio Group
Search Field
Select
Slider
Switch
Tabs
Text Field
Tooltip

import { useState } from "react";
import { useFilter } from "react-aria-components";
import { SearchField } from "@/components/ui/search-field";

const components = [
  "Button",
  "Calendar",
  "Checkbox",
  "Combo Box",
  "Date Picker",
  "Dialog",
  "Menu",
  "Number Field",
  "Popover",
  "Radio Group",
  "Search Field",
  "Select",
  "Slider",
  "Switch",
  "Tabs",
  "Text Field",
  "Tooltip",
];

export default function SearchFieldControlled() {
  const [query, setQuery] = useState("");
  const { contains } = useFilter({ sensitivity: "base" });
  const results = components.filter((c) => contains(c, query));
  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <SearchField
        aria-label="Filter components"
        placeholder="Filter components…"
        value={query}
        onChange={setQuery}
      />
      <p className="text-muted-foreground text-xs" aria-live="polite">
        {results.length} of {components.length} components
      </p>
      <ul className="flex flex-wrap gap-1.5">
        {results.map((c) => (
          <li key={c} className="rounded-md border px-2 py-0.5 text-xs">
            {c}
          </li>
        ))}
      </ul>
    </div>
  );
}

Async search

Fetch results in an effect keyed on the query and abort stale requests, so fast typing never shows out-of-order results. Show a Spinner while loading and an empty state when nothing matches.

Help center

import { useEffect, useState } from "react";
import { SearchField } from "@/components/ui/search-field";
import { Spinner } from "@/components/ui/spinner";

const articles = [
  "Export reports to CSV",
  "Invite teammates to a workspace",
  "Set up single sign-on (SAML)",
  "Rotate API keys",
  "Change your billing email",
  "Configure webhooks",
  "Restore a deleted project",
];

async function searchArticles(query: string, signal: AbortSignal) {
  await new Promise((resolve, reject) => {
    const t = setTimeout(resolve, 500);
    signal.addEventListener("abort", () => {
      clearTimeout(t);
      reject(signal.reason);
    });
  });
  return articles.filter((a) => a.toLowerCase().includes(query.toLowerCase()));
}

export default function SearchFieldAsync() {
  const [query, setQuery] = useState("");
  const [results, setResults] = useState<string[]>([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    if (!query.trim()) {
      setResults([]);
      setLoading(false);
      return;
    }
    const controller = new AbortController();
    setLoading(true);
    searchArticles(query, controller.signal)
      .then((r) => {
        setResults(r);
        setLoading(false);
      })
      .catch(() => {});
    return () => controller.abort();
  }, [query]);

  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <SearchField
        label="Help center"
        placeholder="Search articles…"
        value={query}
        onChange={setQuery}
      />
      <div aria-live="polite" className="text-sm">
        {loading ? (
          <p className="flex items-center gap-2 text-muted-foreground">
            <Spinner size="xs" label="Searching" />
            Searching…
          </p>
        ) : query.trim() && results.length === 0 ? (
          <p className="text-muted-foreground">No articles match “{query}”.</p>
        ) : (
          <ul className="flex flex-col gap-1">
            {results.map((r) => (
              <li key={r}>{r}</li>
            ))}
          </ul>
        )}
      </div>
    </div>
  );
}

Disabled and read only

isDisabled dims the field and disables the clear button. isReadOnly keeps a saved query visible and selectable, and also disables clearing.

Search logs

Search is unavailable while logs are being indexed.

Saved query

import { SearchField } from "@/components/ui/search-field";

export default function SearchFieldDisabled() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-5">
      <SearchField
        label="Search logs"
        isDisabled
        description="Search is unavailable while logs are being indexed."
      />
      <SearchField label="Saved query" isReadOnly defaultValue="status:500" />
    </div>
  );
}

Without onSubmit, Enter submits the surrounding form natively and the query is sent under its name, like a classic ?q= search. isRequired and minLength use native validation. Give the form role="search" so it's exposed as a search landmark.

import { useState } from "react";
import { Form } from "react-aria-components";
import { Button } from "@/components/ui/button";
import { SearchField } from "@/components/ui/search-field";

export default function SearchFieldForm() {
  const [submitted, setSubmitted] = useState<string | null>(null);
  return (
    <Form
      role="search"
      className="flex w-full max-w-sm flex-col gap-3"
      onSubmit={(e) => {
        e.preventDefault();
        const q = String(new FormData(e.currentTarget).get("q"));
        setSubmitted(`/search?q=${encodeURIComponent(q)}`);
      }}
    >
      <div className="flex items-start gap-2">
        <SearchField
          aria-label="Search the help center"
          name="q"
          isRequired
          minLength={2}
          placeholder="How do I export data?"
          className="flex-1"
        />
        <Button type="submit">Search</Button>
      </div>
      {submitted && (
        <code className="self-start rounded-md bg-muted px-2 py-1 text-xs">
          {submitted}
        </code>
      )}
    </Form>
  );
}

Recipes

A small filled search in a top bar, focused with / from anywhere on the page, next to icon actions.

Acme

import { BellIcon, CommandIcon } from "lucide-react";
import { useEffect, useRef } from "react";
import { Avatar } from "@/components/ui/avatar";
import { Button } from "@/components/ui/button";
import { SearchField } from "@/components/ui/search-field";

export default function SearchFieldRecipeHeader() {
  const searchRef = useRef<HTMLElement>(null);

  useEffect(() => {
    const onKeyDown = (e: KeyboardEvent) => {
      if (e.key === "/" && !(e.target instanceof HTMLInputElement)) {
        e.preventDefault();
        searchRef.current?.querySelector("input")?.focus();
      }
    };
    window.addEventListener("keydown", onKeyDown);
    return () => window.removeEventListener("keydown", onKeyDown);
  }, []);

  return (
    <header className="flex w-full max-w-2xl items-center gap-3 rounded-xl border bg-card px-3 py-2">
      <div className="flex items-center gap-2 font-semibold text-sm">
        <span className="flex size-6 items-center justify-center rounded-md bg-primary text-primary-foreground">
          <CommandIcon className="size-3.5" />
        </span>
        <span className="hidden sm:inline">Acme</span>
      </div>
      <search ref={searchRef} className="mx-auto w-full max-w-sm">
        <SearchField
          aria-label="Search projects, people and docs"
          placeholder="Search…"
          variant="filled"
          size="sm"
          shortcut="/"
        />
      </search>
      <Button size="icon-sm" variant="ghost" aria-label="Notifications">
        <BellIcon />
      </Button>
      <Avatar size="sm" fallback="NT" colorful alt="Nischal Timalsina" />
    </header>
  );
}

Filterable member list

A search in a card header filtering a list by name and email, with an empty state that clears the query.

OM
Olivia Martin
olivia@acme.dev
Owner
JL
Jackson Lee
jackson@acme.dev
Admin
IN
Isabella Nguyen
bella@acme.dev
Member
WK
William Kim
will@acme.dev
Member
SD
Sofia Davis
sofia@acme.dev
Viewer

import { SearchXIcon } from "lucide-react";
import { useState } from "react";
import { useFilter } from "react-aria-components";
import { Avatar } from "@/components/ui/avatar";
import { Badge } from "@/components/ui/badge";
import { Button } from "@/components/ui/button";
import { SearchField } from "@/components/ui/search-field";

const members = [
  { name: "Olivia Martin", email: "olivia@acme.dev", role: "Owner" },
  { name: "Jackson Lee", email: "jackson@acme.dev", role: "Admin" },
  { name: "Isabella Nguyen", email: "bella@acme.dev", role: "Member" },
  { name: "William Kim", email: "will@acme.dev", role: "Member" },
  { name: "Sofia Davis", email: "sofia@acme.dev", role: "Viewer" },
];

const initials = (name: string) =>
  name
    .split(" ")
    .map((n) => n[0])
    .join("");

export default function SearchFieldRecipeMembers() {
  const [query, setQuery] = useState("");
  const { contains } = useFilter({ sensitivity: "base" });
  const results = members.filter(
    (m) => contains(m.name, query) || contains(m.email, query),
  );

  return (
    <div className="w-full max-w-md rounded-xl border bg-card">
      <div className="flex items-center justify-between gap-3 border-b p-3">
        <SearchField
          aria-label="Search members"
          placeholder="Search by name or email…"
          size="sm"
          value={query}
          onChange={setQuery}
          className="flex-1"
        />
        <Button size="sm">Invite</Button>
      </div>
      {results.length > 0 ? (
        <ul className="divide-y">
          {results.map((m) => (
            <li key={m.email} className="flex items-center gap-3 px-3 py-2.5">
              <Avatar
                size="sm"
                colorful
                alt={m.name}
                fallback={initials(m.name)}
              />
              <div className="min-w-0 flex-1">
                <p className="truncate font-medium text-sm">{m.name}</p>
                <p className="truncate text-muted-foreground text-xs">
                  {m.email}
                </p>
              </div>
              <Badge variant="soft" color="neutral">
                {m.role}
              </Badge>
            </li>
          ))}
        </ul>
      ) : (
        <div className="flex flex-col items-center gap-2 p-8 text-center">
          <SearchXIcon className="size-5 text-muted-foreground" />
          <p className="font-medium text-sm">No members found</p>
          <p className="text-muted-foreground text-xs">
            Nobody matches “{query}”.
          </p>
          <Button size="sm" variant="outline" onPress={() => setQuery("")}>
            Clear search
          </Button>
        </div>
      )}
    </div>
  );
}

Accessibility

The input has type="search", so assistive technology announces it as a search field.
Always provide a label: label, aria-label, or aria-labelledby. The search icon is decorative.
The clear button is labelled "Clear search" (localized). It's skipped in the tab order because Esc does the same thing, and pressing it keeps focus in the input so the mobile keyboard stays open.
The shortcut hint is visual only. If you bind a global shortcut, avoid keys users type into other inputs; the header recipe ignores / while an input is focused.
Wrap search areas in role="search" (on a <form> or a <div>) to create a search landmark.
For live results, announce counts or "no results" with an aria-live="polite" region.

Keyboard

Key	Action
`Enter`	Calls `onSubmit`, or submits the surrounding form when there's no `onSubmit`
`Esc`	Clears the field and calls `onClear`. When already empty, the key passes through, for example to close a dialog

Styling

Data attributes

On the SearchField root. Children can react with group-data-*/field: variants; the component itself uses group-data-empty/field: to swap the shortcut hint and the clear button.

Attribute	Present when
`data-empty`	The query is empty
`data-disabled`	`isDisabled` is true
`data-readonly`	`isReadOnly` is true
`data-required`	`isRequired` is true
`data-invalid`	Validation failed, or `isInvalid` is true

On the FieldGroup: data-hovered, data-focus-within, data-focus-visible, data-invalid and data-disabled.

Slots

`data-slot`	Element
`search-field`	Root
`label`, `description`, `field-error`	Field text
`field-group`	Visible box
`field-input`	`<input>`

The box comes from fieldVariants in field.tsx; see Text Field. className also accepts a function of the render state (isEmpty, isDisabled, isInvalid, isReadOnly, isRequired, state).

API Reference

SearchField

Prop

Type

Also accepts every prop of React Aria's SearchField.

Combo Box — search that ends in choosing an option.
Command Palette — a global search and command launcher.
Text Field — the shared field building blocks.
Kbd — for showing shortcuts elsewhere.