Provides <.input> and <.input_group> components for text-based form fields.

The <.input> component renders a labeled <input> element together with optional description, helper text, and error messages. It composes with prefix and suffix slots, both inside and outside the field, so icons, static text, dropdowns, and action buttons can be attached without breaking border alignment. The component binds directly to Phoenix.HTML.FormField structs for changeset-driven forms or accepts a plain name/value for standalone use.

The <.input_group> component visually joins multiple inputs or related controls (selects, buttons) into a single connected control with shared borders and rounding.

Usage

Render an input by providing a name. A label is recommended so the field has a visible association for the user:

<.input name="username" label="Username" placeholder="Enter username..." />

Most fields combine a label with a placeholder, helper text, and a specific input type:

<.input
  name="email"
  type="email"
  label="Email"
  description="We'll send a confirmation link here."
  help_text="We never share your email."
  placeholder="you@example.com"
/>

Sizes

The size attribute scales the field height, horizontal padding, and font size. The default is "md":

<.input name="input_xs" size="xs" placeholder="Extra Small" />
<.input name="input_sm" size="sm" placeholder="Small" />
<.input name="input_md" size="md" placeholder="Medium (Default)" />
<.input name="input_lg" size="lg" placeholder="Large" />
<.input name="input_xl" size="xl" placeholder="Extra Large" />

Input Types

The type attribute maps directly to the underlying <input>'s HTML type. Pick the type that matches the value being collected so the browser provides the right on-screen keyboard, validation hints, and native picker UI:

<.input type="email" name="email" label="Email" />
<.input type="password" name="password" label="Password" />
<.input type="search" name="site_search" placeholder="Search site..." />
<.input type="number" name="count" label="Quantity" min="1" max="10" />
<.input type="date" name="appointment" label="Appointment Date" />
<.input type="time" name="start_at" label="Start Time" />

Setting type="hidden" renders only a bare <input type="hidden"> with no surrounding label, affixes, or error UI. This is useful for carrying values that must round-trip with a form but should not be visible to the user.

Labels, Description, and Helper Text

The label area can carry up to three distinct strings:

• label: the primary label rendered above the field.
• sublabel: short inline text rendered next to the label, typically a state hint such as "(required)" or "(optional)".
• description: longer guidance rendered between the label and the field.

Helper text rendered below the field uses the help_text attribute:

<.input
  name="api_key"
  label="API Key"
  sublabel="(required)"
  description="Used to authenticate requests against your account."
  help_text="Stored encrypted at rest. Rotate keys from your account settings."
/>

Form Integration

The component supports two binding modes: a Phoenix.HTML.FormField struct via field (changeset-driven forms) or a plain name (standalone inputs).

Bind to a form field

When field is set, the component derives id, name, value, and errors from the form field struct. Errors are translated and rendered automatically when the field has been touched (Phoenix.Component.used_input?/1):

<.form :let={f} for={@form}>
  <.input field={f[:email]} type="email" label="Email" />
  <.input field={f[:password]} type="password" label="Password" />
</.form>

This mode handles nested input names (user[email]) and validation errors with no extra wiring.

Standalone input

When you don't have a changeset, pass name, optionally value, and any error list directly:

<.input name="q" placeholder="Search..." value={@query} />
<.input name="email" type="email" value={@email} errors={@errors} />

Input States

Disabled

Disabled inputs cannot be focused or edited and are styled with reduced contrast. Disabling a parent <fieldset> cascades to descendant inputs through HTML's native :disabled semantics:

<.input name="locked" value="Cannot change" disabled />

<fieldset disabled>
  <.input name="email" value="user@example.com" />
  <.input name="phone" value="+1 555 123 4567" />
</fieldset>

Readonly

A readonly input still receives focus and can be selected/copied, but its value cannot be edited. Pass readonly through the global rest attribute:

<.input name="reference" value="REF-2025-0042" readonly />

Errors

When the errors list is non-empty (or the bound form field has errors), the field renders with the danger color and each message is shown below the input:

<.input
  name="email"
  value="invalid@"
  errors={["Must be a valid email address."]}
/>

When using field, errors are pulled from field.errors and translated through the configured Gettext backend.

Inner Affixes

The :inner_prefix and :inner_suffix slots inject content inside the field border, sharing the input's focus ring. Use them for inline icons, currency symbols, password reveal toggles, and inline indicators:

<!-- Email field with leading icon -->
<.input name="email" placeholder="user@example.com">
  <:inner_prefix>
    <.icon name="hero-at-symbol" class="icon" />
  </:inner_prefix>
</.input>

<!-- Password with reveal toggle -->
<.input name="password" type="password" value="secretpassword">
  <:inner_suffix>
    <.button variant="tertiary" size="icon-sm" title="Show password">
      <.icon name="hero-eye" class="icon" />
    </.button>
  </:inner_suffix>
</.input>

<!-- Static text prefix -->
<.input name="subdomain" placeholder="yourdomain">
  <:inner_prefix class="pointer-events-none text-tertiary">https://www.</:inner_prefix>
</.input>

<!-- Inline loading indicator while a search runs -->
<.input name="q" placeholder="Searching..." disabled>
  <:inner_suffix>
    <.loading variant="ring-bg" />
  </:inner_suffix>
</.input>

Both inner slots accept multiple entries and an optional class for per-slot overrides.

Outer Affixes

The :outer_prefix and :outer_suffix slots attach content outside the field's border. The component automatically rounds the leading/trailing corners of the affix and overlaps borders for a single seamless control. Use them for action buttons, select dropdowns, or static unit labels that are conceptually paired with the input but distinct from its value:

<!-- Invite form with a trailing send button -->
<.input name="invite_email" placeholder="user@example.com">
  <:inner_prefix>
    <.icon name="hero-at-symbol" class="icon" />
  </:inner_prefix>
  <:outer_suffix>
    <.button variant="solid" color="primary">
      <.icon name="hero-paper-airplane" class="icon" /> Invite
    </.button>
  </:outer_suffix>
</.input>

<!-- Currency picker on the leading edge, action on the trailing edge -->
<.input name="amount" placeholder="100.00">
  <:inner_prefix>$</:inner_prefix>
  <:outer_prefix>
    <select class="h-full w-full rounded-l-lg border-none focus:ring-0 px-2">
      <option value="USD">USD</option>
      <option value="CAD">CAD</option>
    </select>
  </:outer_prefix>
  <:outer_suffix>
    <.button variant="soft" color="primary">Check Balance</.button>
  </:outer_suffix>
</.input>

<!-- Domain field framed by static text -->
<.input name="site" placeholder="mysite">
  <:outer_prefix class="px-2 text-tertiary">https://</:outer_prefix>
  <:outer_suffix class="px-2 text-tertiary">.example.com</:outer_suffix>
</.input>

<!-- Numeric input with a unit -->
<.input name="weight" type="number" placeholder="50">
  <:outer_suffix class="px-2 text-tertiary">kg</:outer_suffix>
</.input>

Input Groups

<.input_group> joins multiple inputs (and adjacent controls like buttons or selects) into one connected control. The group strips internal rounding and collapses adjacent borders so the children read as a single unit:

<!-- First and last name -->
<.input_group label="Full Name">
  <.input name="first_name" placeholder="First Name" />
  <.input name="last_name" placeholder="Last Name" />
</.input_group>

<!-- Two inputs separated by a static label -->
<.input_group label="Price Range">
  <.input name="min_price" placeholder="Min price">
    <:inner_prefix>$</:inner_prefix>
  </.input>
  <div class="shrink-0 bg-emphasis border-y border-base shadow-xs self-stretch flex items-center justify-center px-2 text-foreground-softest">
    to
  </div>
  <.input name="max_price" placeholder="Max price">
    <:inner_prefix>$</:inner_prefix>
  </.input>
</.input_group>

<!-- Card number, expiry, and CVC sharing one connected control -->
<.input_group>
  <.input name="card_number" placeholder="Card Number">
    <:inner_prefix><.icon name="hero-credit-card" class="icon" /></:inner_prefix>
  </.input>
  <.input name="expiry" placeholder="MM / YY" class="w-24" />
  <.input name="cvc" placeholder="CVC" class="w-20" />
</.input_group>

Constraining Field Width

By default the field fills the width of its container. To narrow only the field while keeping the label, description, and helper text at their natural width, apply a width utility to any ancestor that targets [data-part=field-root]:

<div class="**:data-[part=field-root]:max-w-xs">
  <.input label="Postal code" description="Used for billing" name="zip" />
</div>

This pattern works uniformly across all Fluxon input-shaped form components.

Examples

Login form with changeset binding

<.form :let={f} for={@form} phx-submit="sign_in" phx-change="validate">
  <.input field={f[:email]} type="email" label="Email" autocomplete="email" required />
  <.input field={f[:password]} type="password" label="Password" autocomplete="current-password" required>
    <:inner_suffix>
      <.button type="button" variant="tertiary" size="icon-sm" phx-click={JS.dispatch("toggle-password")}>
        <.icon name="hero-eye" class="icon" />
      </.button>
    </:inner_suffix>
  </.input>

  <.button type="submit" color="primary">Sign in</.button>
</.form>

Top-bar search with submit button

<.input name="q" type="search" placeholder="Search articles..." value={@query} phx-debounce="200">
  <:inner_prefix>
    <.icon name="hero-magnifying-glass" class="icon" />
  </:inner_prefix>
  <:outer_suffix>
    <.button color="primary" phx-click="search">Search</.button>
  </:outer_suffix>
</.input>

Invite teammates by email

<.input
  field={@form[:email]}
  type="email"
  label="Invite teammates"
  placeholder="teammate@company.com"
  description="They'll receive a sign-up link valid for 7 days."
>
  <:inner_prefix>
    <.icon name="hero-at-symbol" class="icon" />
  </:inner_prefix>
  <:outer_suffix>
    <.button color="primary" phx-disable-with="Sending...">
      Send invite
    </.button>
  </:outer_suffix>
</.input>

Money amount with a currency picker

<.input field={@form[:amount]} type="number" label="Amount" min="0" step="0.01">
  <:outer_prefix>
    <select name="currency" class="h-full w-full rounded-l-base border-none focus:ring-0 px-2">
      <option value="USD">USD</option>
      <option value="EUR">EUR</option>
      <option value="GBP">GBP</option>
    </select>
  </:outer_prefix>
</.input>

Address group: postal code + city

<.input_group label="Address" help_text="We use this to estimate shipping.">
  <.input field={@form[:postal_code]} placeholder="Postal code" class="w-32" />
  <.input field={@form[:city]} placeholder="City" />
</.input_group>

Date and time range

<.input_group label="When">
  <.input field={@form[:starts_on]} type="date" class="w-44" />
  <.input field={@form[:starts_at]} type="time" class="w-32" />
</.input_group>