# Input

## Overview

The standard text field component. Use it for all single-line text inputs: names, emails, search queries, codes. Integrates seamlessly with `react-hook-form` via the `{...field}` spread pattern.

---

## When to Use

- Single-line text input in forms
- Search bars (pair with the `relative`/absolute icon pattern)
- Inline editing fields

## When NOT to Use

- Multi-line text entry — use `<Textarea>` instead.
- Numeric ranges — use `<Slider>` instead.
- Date selection — use `<Calendar>` instead.
- Never use native `<input>` — always use `<Input>` from `xertica-ui`.

---

## Props

All native `<input>` HTML attributes are forwarded.

| Prop          | Type                   | Default  | Description                                                       |
| ------------- | ---------------------- | -------- | ----------------------------------------------------------------- |
| `type`        | `string`               | `'text'` | Input type: `text`, `email`, `password`, `number`, `search`, etc. |
| `size`        | `'sm' \| 'md' \| 'lg'` | `'md'`   | Size variant controlling height, padding, and font size.          |
| `placeholder` | `string`               | —        | Placeholder text                                                  |
| `disabled`    | `boolean`              | `false`  | Disables interaction                                              |
| `className`   | `string`               | —        | Additional CSS classes                                            |

### Standardized Sizing Scale

All form input components (`Input`, `SelectTrigger`, `Textarea`, `Search`) share the same sizing scale:

| Size | Height        | Padding     | Font        |
| ---- | ------------- | ----------- | ----------- |
| `sm` | `h-8` (32px)  | `px-2 py-1` | `text-sm`   |
| `md` | `h-10` (40px) | `px-3 py-2` | `text-base` |
| `lg` | `h-12` (48px) | `px-4 py-3` | `text-base` |

This ensures all form elements align perfectly when placed side-by-side in grid layouts.

---

## Examples

### Basic Text Input

```tsx
import { Input } from 'xertica-ui/ui';

<Input placeholder="Enter your name" />;
```

### With Label (standalone)

```tsx
import { Input, Label } from 'xertica-ui/ui';

<div className="grid gap-2">
  <Label htmlFor="email">Email</Label>
  <Input id="email" type="email" placeholder="you@example.com" />
</div>;
```

### Search Input with Icon

```tsx
import { Search } from 'lucide-react';

<div className="relative w-full max-w-sm">
  <Search className="absolute left-2.5 top-2.5 size-4 text-muted-foreground" />
  <Input placeholder="Search..." className="pl-8" />
</div>;
```

### Inside react-hook-form

```tsx
<FormField
  control={form.control}
  name="email"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Email</FormLabel>
      <FormControl>
        <Input type="email" placeholder="you@example.com" {...field} />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

---

## Accessibility

- Always pair with a `<Label>` component. Use the `htmlFor` prop on the label and `id` on the input to link them.
- If a visual label is not possible (e.g., search bars), **you must provide an `aria-label`** prop:
  ```tsx
  <Input aria-label="Search items" placeholder="Search..." />
  ```
- Use the `disabled` prop to indicate non-interactive fields correctly to assistive technologies.
- Maintain a minimum 1.5:1 contrast for placeholder text (handled by design system defaults).

---

## AI Rules

- **Never** use native `<input>` — always use `<Input>` from `xertica-ui`.
- **Sizing** — The default size is `md` (h-10, 40px). Use the same `size` prop across `Input`, `SelectTrigger`, `Textarea`, and `Search` to ensure consistent alignment.
- **Accessibility Requirement**: Always provide a `<Label>` or an explicit `aria-label`. Placeholder text is NOT an accessible name.
- When in a form with `react-hook-form`, **always spread `{...field}`** on the `<Input>` inside `<FormControl>`.
- Search inputs always use the `relative` + `absolute icon` + `pl-8` pattern — never place the icon outside the input container.
- Do not add `border`, `rounded`, or `bg-` classes to override the input style — it already inherits from the design system tokens.

---

## Related Components

- [`Textarea`](./textarea.md) — Multi-line text input
- [`Form`](./form.md) — Form integration context
- [`Label`](./label.md) — Always pair with a Label for accessibility
- [`Search`](./search.md) — Pre-built search input component