PUI.Input (pui v1.0.0-beta.14)

Copy Markdown

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

Summary

Functions

checkbox(assigns)

Renders a checkbox control.

generate_id(prefix \\ "input")
input(assigns)

Renders a styled single-line HTML input.

label(assigns)

Renders a standalone form label.

map_field(assigns)
radio(assigns)

Renders a radio input for a radio group.

switch(assigns)

Renders a switch-style boolean control.

textarea(assigns)

Renders a multi-line textarea.

Functions

checkbox(assigns)

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(prefix \\ "input")

input(assigns)

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(assigns)

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(assigns)

radio(assigns)

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(assigns)

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(assigns)

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"].