# SearchInput

> A search field with a clear button, Escape to clear and an optional shortcut hint.

Category: Forms · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/search-input

Use SearchInput to filter lists and tables or to start a search. It is a native search input (role searchbox) with a leading icon, a clear button once there is text, and a keyboard hint while empty. Pair with SearchableList or FilterBar for complete filtering patterns.

## Import

```tsx
import { SearchInput } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { SearchInput } from '@bindshq/stance-react';

export function Basic() {
  return (
    <div style={{ width: '100%', maxWidth: 360 }}>
      <SearchInput aria-label="Search templates" placeholder="Search templates" shortcut="/" />
    </div>
  );
}
```

### Filtering a list

```tsx
import * as React from 'react';
import { SearchInput } from '@bindshq/stance-react';

const users = ['Priya Raman', 'Tom Okafor', 'Lena Fischer', 'Marco Bianchi', 'Aiko Tanaka'];

export function Filtering() {
  const [query, setQuery] = React.useState('');
  const results = users.filter((u) => u.toLowerCase().includes(query.toLowerCase()));
  return (
    <div style={{ display: 'grid', gap: 12, width: '100%', maxWidth: 360 }}>
      <SearchInput
        aria-label="Search organisation users"
        placeholder="Search users"
        value={query}
        onValueChange={setQuery}
      />
      <p role="status" style={{ margin: 0, fontSize: 13 }}>
        {results.length} {results.length === 1 ? 'user' : 'users'}
      </p>
      <ul style={{ margin: 0, paddingLeft: 18, fontSize: 14 }}>
        {results.map((u) => (
          <li key={u}>{u}</li>
        ))}
      </ul>
    </div>
  );
}
```

### Loading and sizes

```tsx
import { SearchInput } from '@bindshq/stance-react';

export function Loading() {
  return (
    <div style={{ display: 'grid', gap: 12, width: '100%', maxWidth: 360 }}>
      <SearchInput size="sm" aria-label="Search (small)" defaultValue="NDA" />
      <SearchInput aria-label="Search contracts" defaultValue="Master services" loading />
      <SearchInput
        size="lg"
        aria-label="Search (large)"
        placeholder="Search everything"
        shortcut="⌘K"
      />
    </div>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| SearchInput | `value` | `string` | None | Controlled value. |
| SearchInput | `defaultValue` | `string` | `''` | Initial value. |
| SearchInput | `onValueChange` | `(value: string) => void` | None | Called on every change. |
| SearchInput | `onSearch` | `(value: string) => void` | None | Called on Enter. |
| SearchInput | `onClear` | `() => void` | None | Called when cleared by button or Escape. |
| SearchInput | `shortcut` | `string` | None | Keyboard hint shown while empty, e.g. "⌘K". |
| SearchInput | `loading` | `boolean` | `false` | Replace the search icon with a spinner. |
| SearchInput | `clearLabel` | `string` | `'Clear search'` | Clear button label. |
| SearchInput | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Control height. |

## Accessibility

- Renders <input type="search">, exposed as a searchbox.
- Provide a label with aria-label or FormField; the placeholder is not a label.
- Clearing returns focus to the field so typing can continue.
- Announce result counts near the results with a live region (for example "12 templates").

## Keyboard

| Keys | Action |
| --- | --- |
| `Escape` | Clears the value (when not empty). |
| `Enter` | Calls onSearch. |

## Related

- https://stanceui.com/components/input
- https://stanceui.com/components/searchable-list
- https://stanceui.com/components/filter-bar
- https://stanceui.com/components/command-palette