# Search

## Overview

A pre-built search input with a built-in search icon and clear button. A convenience component built on top of `<Input>` that handles the common search field pattern with a consistent size scale.

---

## When to Use

- Search fields in headers, sidebar filters, and CRUD filter rows
- When a plain `<Input>` + manual icon positioning is redundant

---

## Props

| Prop                 | Type                                         | Default | Required | Description                                                         |
| -------------------- | -------------------------------------------- | ------- | -------- | ------------------------------------------------------------------- |
| `value`              | `string`                                     | —       | No       | Controlled value                                                    |
| `onChange`           | `React.ChangeEventHandler<HTMLInputElement>` | —       | No       | Native change handler                                               |
| `onSearch`           | `(value: string) => void`                    | —       | No       | Called with the string value on every keystroke                     |
| `onClear`            | `() => void`                                 | —       | No       | Called when the × button is clicked or Escape is pressed            |
| `placeholder`        | `string`                                     | —       | No       | Input placeholder text                                              |
| `size`               | `'sm' \| 'md' \| 'lg'`                       | `'md'`  | No       | Height preset — matches the Input/Select size scale (h-8/h-10/h-12) |
| `containerClassName` | `string`                                     | —       | No       | CSS classes for the outer wrapper div                               |
| `className`          | `string`                                     | —       | No       | CSS classes for the input element                                   |

---

## Examples

### Controlled Search

```tsx
import { Search } from 'xertica-ui/ui';
import { useState } from 'react';

const [query, setQuery] = useState('');

<Search
  value={query}
  onSearch={setQuery}
  onClear={() => setQuery('')}
  placeholder="Search members..."
  className="w-full max-w-sm"
/>;
```

### Size Variants

```tsx
<Search size="sm" placeholder="Small search" />
<Search size="md" placeholder="Default search" />
<Search size="lg" placeholder="Large search" />
```

---

## Alternative: Manual Composition

When `Search` component is not available, use the standard Input pattern:

```tsx
import { Input } from 'xertica-ui/ui';
import { Search as SearchIcon } from 'lucide-react';

<div className="relative w-full max-w-sm">
  <SearchIcon className="absolute left-2.5 top-2.5 size-4 text-muted-foreground" />
  <Input
    value={query}
    onChange={e => setQuery(e.target.value)}
    placeholder="Search..."
    className="pl-8"
  />
</div>;
```

---

## AI Rules

- **Sizing** — Search defaults to `md` (h-10, 40px), matching Input, SelectTrigger, and Textarea. Use the same `size` across all form elements for consistent alignment.
- Use `onSearch` for simple string callbacks; use `onChange` when you need the full event object.
- The clear button (×) only appears when the input has content — it is hidden when empty.
- Pressing `Escape` also triggers `onClear`.
- When using the manual composition pattern (Input + icon), always use `relative` on the wrapper + `absolute` on the icon + `pl-8` on the Input.