# Search input

> The field at the top of every list: ⌘K focuses it from anywhere, search runs after a pause, the magnifier blurs into a spinner while it loads.

Search fields usually wire their own debounce, shortcut and spinner, and the shortcut hint overlaps the text. This one runs onSearch after a pause (Enter runs it at once), focuses on ⌘K or "/" from anywhere on the page, steps its key hint aside as you type, and turns the magnifier into a spinner while results load.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/search-input.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `ui-interaction-motion`
- Docs and live preview: https://hairlineui.com/ui/search-input
- Registry item (source): https://hairlineui.com/r/search-input.json

## Usage

```tsx
import { SearchInput } from "@/components/ui/search-input";

<SearchInput placeholder="Search customers" loading={isFetching} onSearch={(q) => setQuery(q)} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onSearch` | `(query: string) => void` | – | After `debounce` ms without typing, and at once on Enter. |
| `debounce` | `number` | `250` | Wait in ms. |
| `loading` | `boolean` | `false` | Spinner in place of the magnifier. |
| `shortcut` | `"mod+k" \| "/" \| null` | `"mod+k"` | Key that focuses the field. |
| `...Input props` | `InputProps` | – | label, size, value, onValueChange and every native prop. |

## States

- **rest**: Magnifier, placeholder and the ⌘K hint.
- **typing**: The hint folds away (320ms) and the clear button folds in.
- **loading**: The magnifier blurs into a spinner (scale 0.6, 3px).
- **focused by shortcut**: The field takes focus and selects its text.

## What it handles

Each search box ends up with its own timer, its own keyboard listener and a spinner bolted on beside it. This one has them built in and keeps them out of each other's way.

- **Debounced search**: Runs after 250ms without typing; Enter runs it immediately.
- **A real shortcut**: ⌘K / Ctrl K or "/" focuses and selects the field, never while you type elsewhere.
- **Loading in place**: The magnifier blurs into a spinner and back.
- **Clear and Escape**: The clear button folds in with the first letter; Escape leaves the field.

## Replaces

debounce hook, keyboard shortcut listener, loading spinner, clear button

## Where it fits

- **List and table headers**: Search above customers, invoices or files.
- **Docs and help centres**: A "/" shortcut like GitHub and MDN.
- **App top bars**: A ⌘K field that focuses from anywhere.
- **Pickers and sidebars**: Filter a long list as you type.

## Notes

- Shares field.tsx with every text control: one surface, one focus ring, one way of showing hints and errors.
- role="searchbox"; the shortcut hint is aria-hidden (the key is a convenience, not a name).
- The browser's own cancel button is hidden in favour of the folding one.

License: MIT (https://hairlineui.com/license#components)