# Input

A native text input in the theme's control chrome, with a two-way value.

```ehtml Example
import { Input } from "@elements/ui/input";

<Input value={form.email} type="email" placeholder="you@example.com" />
<Input value={form.name} invalid={!!form.error} size="sm" />
<Input type="file" multiple files={form.photos} attrs={{ accept: "image/*" }} />
```

## Parts

| Part | What it is |
|---|---|
| `.input` | The `<input>`. Usable without the template: class="input is-sm". |

## Attributes

| Attribute | Type | Default | Description |
|---|---|---|---|
| `value` | `string` (two-way) | `""` | The text. Bind it to state; typing writes back. |
| `files` | `File[]` (two-way) | `[]` | type=file: the picked files, read by the runtime. |
| `type` | `"text" \| "email" \| "password" \| "search" \| "tel" \| "url" \| "number" \| "date" \| "time" \| "datetime-local" \| "month" \| "week" \| "file"` | `"text"` | The native type: keyboards and validation follow it. |
| `multiple` | `boolean` | `false` | type=file: allow several files. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height, padding and type size from the control tokens. |
| `placeholder` | `string` | `""` | Hint text shown while empty. |
| `name` | `string` | `""` | Form field name. |
| `invalid` | `boolean` | `false` | Sets aria-invalid and the danger border and ring. |
| `disabled` | `boolean` | `false` | Native disabled. |
| `readonly` | `boolean` | `false` | Focusable and selectable, not editable. |
| `required` | `boolean` | `false` | Native required: the form will not submit while empty. |
| `class` | `string` | `""` | Extra classes on the input. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Any other attribute: id, minlength, pattern, autocomplete, inputmode, aria-\*, data-\*. |
| `onValueChange` | `(value: string, details: ChangeDetails) => void` | `() => {}` | Called on each edit before the value changes, with details: { reason: "none", event, cancel(), allowPropagation(), isCanceled, isPropagationAllowed }. details.cancel() keeps the old value in the box and the binding. Not called for changes the caller makes. |
| `oninput` | `(e: InputEvent) => void` | `() => {}` | Each edit. |
| `onchange` | `(e: Event) => void` | `() => {}` | Committed change (blur, Enter, file picked). |
| `onfocus / onblur` | `(e: FocusEvent) => void` | `() => {}` | Focus events. |
| `onkeydown` | `(e: KeyboardEvent) => void` | `() => {}` | Key presses. |

## Keyboard

| Keys | Action |
|---|---|
| `Enter` | Submits the form the input is in. |
| `Tab` | Moves to the next control. A disabled input is skipped. |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-size` | `"sm" \| "md" \| "lg"` | input |
| `data-invalid` | present while invalid | input |
| `data-disabled` | present while disabled | input |

## Accessibility

- A native `<input>`: typing, selection, autofill, mobile keyboards and form validation are the browser's.
- invalid sets aria-invalid="true"; inside a Field the field sets it and wires aria-describedby to the description and error.
- Label it with `<Label htmlFor>` and an id in attrs, or put it in a `<Field label>`.
- Focus shows the theme ring as a box-shadow; focus, invalid and disabled never change the input's size.

## See also

- [ButtonGroup](button-group): Related buttons, or an input and its buttons, joined into one control.
- [InputGroup](input-group): An Input or Textarea with icons, text and buttons inside one box.
- [Textarea](textarea): A native multi-line input that grows with its content, between rows and maxRows.
- [Field](field): A label, a control, a description and an error wired together, with native validation that never moves the layout.
- [Label](label): A native label for a control, which dims when the control is disabled.
- [NativeSelect](native-select): The browser's own select, styled as a control. Native pickers on phones, no script needed.