# `PUI.Input`

Form controls for text inputs, checkboxes, radios, switches, labels, and textareas.

`PUI.Input` collects the core form primitives used across PUI. The text-based
controls support direct binding to `Phoenix.HTML.FormField` values, and all
form controls can render validation feedback through the `errors` attribute.

## Field-based forms

    <.form for={@form} phx-change="validate">
      <.input field={@form[:email]} type="email" label="Email" />
      <.textarea field={@form[:notes]} label="Notes" rows="5" />
    </.form>

When `field` is provided, the component derives its `id`, `name`, and `value`
from the form field. Errors are shown only after
`Phoenix.Component.used_input?/1` marks the field as used.

## Manual errors

    <.checkbox
      id="terms"
      name="terms"
      label="I agree to the terms"
      errors={["Please accept the terms."]}
    />

    <.switch
      id="notifications"
      name="notifications"
      label="Enable notifications"
      errors={["Turn this on before continuing."]}
    />

## Included components

- `input/1` for single-line HTML inputs
- `textarea/1` for multi-line text
- `checkbox/1` for boolean choices
- `radio/1` for single-choice groups
- `switch/1` for toggle-style boolean controls
- `label/1` for standalone labels

# `checkbox`

Renders a checkbox control.

Use `label` for the default checkbox-plus-label layout, or omit it when you
need complete control over the surrounding markup. Validation messages can be
supplied with the `errors` attribute.

## Examples

    <.checkbox id="terms" name="terms" label="I agree to the terms" />

    <.checkbox
      id="terms"
      name="terms"
      label="I agree to the terms"
      errors={["Please accept the terms."]}
    />

## Attributes

* `id` (`:any`) - Defaults to `nil`.
* `label` (`:string`) - Defaults to `nil`.
* `class` (`:string`) - Defaults to `nil`.
* `field` (`Phoenix.HTML.FormField`) - a form field struct retrieved from the form, for example: @form[:email]. Defaults to `nil`.
* `errors` (`:list`) - a list of error strings to display below the checkbox. Defaults to `[]`.
* Global attributes are accepted. Supports all globals plus: `["accept", "autocomplete", "capture", "cols", "disabled", "form", "list", "max", "maxlength", "min", "minlength", "multiple", "pattern", "placeholder", "readonly", "required", "rows", "size", "step", "checked", "name", "value"]`.
## Slots

* `inner_block`

# `generate_id`

# `input`

Renders a styled single-line HTML input.

Use `field={@form[:name]}` to bind the input to a Phoenix form field, or pass
`name`, `value`, and `errors` directly for manual control.

## Examples

    <.input type="email" name="email" label="Email" placeholder="you@example.com" />

    <.input field={@form[:email]} type="email" label="Email" />

    <.input
      name="company"
      label="Company"
      errors={["Please enter a company name."]}
    />

## Attributes

* `id` (`:any`) - Defaults to `nil`.
* `class` (`:string`) - Defaults to `""`.
* `type` (`:string`) - Defaults to `"text"`.
* `label` (`:string`) - Defaults to `nil`.
* `field` (`Phoenix.HTML.FormField`) - a form field struct retrieved from the form, for example: @form[:email]. Defaults to `nil`.
* `errors` (`:list`) - a list of error strings to display below the input. Defaults to `[]`.
* Global attributes are accepted. Supports all globals plus: `["accept", "autocomplete", "capture", "cols", "disabled", "form", "list", "max", "maxlength", "min", "minlength", "multiple", "pattern", "placeholder", "readonly", "required", "rows", "size", "step", "name", "value"]`.

# `label`

Renders a standalone form label.

## Examples

    <.label for="email">Email</.label>

## Attributes

* `class` (`:string`) - Defaults to `""`.
* Global attributes are accepted. Supports all globals plus: `["for"]`.
## Slots

* `inner_block`

# `map_field`

# `radio`

Renders a radio input for a radio group.

Radios typically share a `name` and differ by `value`. When validation fails,
pass `errors` to render a message below the radio control.

## Examples

    <label class="flex items-center gap-3">
      <.radio id="plan-pro" name="plan" value="pro" />
      <span>Pro</span>
    </label>

    <div class="space-y-2">
      <label class="flex items-center gap-3">
        <.radio
          id="plan-starter"
          name="plan"
          value="starter"
          errors={["Please choose a plan."]}
        />
        <span>Starter</span>
      </label>
    </div>

## Attributes

* `id` (`:any`) - Defaults to `nil`.
* `class` (`:string`) - Defaults to `""`.
* `field` (`Phoenix.HTML.FormField`) - a form field struct retrieved from the form, for example: @form[:email]. Defaults to `nil`.
* Global attributes are accepted. Supports all globals plus: `["checked", "name", "value"]`.

# `switch`

Renders a switch-style boolean control.

`switch/1` shares the same `field` and `errors` conventions as the other form
controls, while presenting the boolean input as a compact toggle.

## Examples

    <.switch id="notifications" name="notifications" label="Enable notifications" />

    <.switch
      id="notifications"
      name="notifications"
      label="Enable notifications"
      errors={["Turn this on before continuing."]}
    />

## Attributes

* `id` (`:any`) - Defaults to `nil`.
* `class` (`:string`) - Defaults to `""`.
* `label` (`:string`) - Defaults to `nil`.
* `field` (`Phoenix.HTML.FormField`) - a form field struct retrieved from the form, for example: @form[:email]. Defaults to `nil`.
* `errors` (`:list`) - a list of error strings to display below the switch. Defaults to `[]`.
* Global attributes are accepted. Supports all globals plus: `["accept", "capture", "cols", "disabled", "form", "list", "max", "maxlength", "min", "minlength", "multiple", "pattern", "placeholder", "readonly", "required", "rows", "size", "step", "name", "value"]`.

# `textarea`

Renders a multi-line textarea.

`textarea/1` supports manual values and errors, or it can bind to a Phoenix
form field to inherit the field's `id`, `name`, `value`, and validation state.

## Examples

    <.textarea label="Notes" name="notes" rows="5" />

    <.textarea field={@form[:notes]} label="Notes" rows="5" />

    <.textarea
      name="notes"
      label="Notes"
      errors={["Please add a short note."]}
    />

## Attributes

* `id` (`:any`) - Defaults to `nil`.
* `class` (`:string`) - Defaults to `""`.
* `label` (`:string`) - Defaults to `nil`.
* `field` (`Phoenix.HTML.FormField`) - a form field struct retrieved from the form, for example: @form[:email]. Defaults to `nil`.
* `errors` (`:list`) - a list of error strings to display below the textarea. Defaults to `[]`.
* Global attributes are accepted. Supports all globals plus: `["accept", "capture", "cols", "disabled", "form", "list", "max", "maxlength", "min", "minlength", "multiple", "pattern", "placeholder", "readonly", "required", "rows", "size", "step", "name", "value"]`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*