Toggle switch for on/off settings that take effect immediately.

Renders a styled checkbox input as a sliding track and thumb, with built-in label, sublabel, and description rendering. Integrates directly with Phoenix forms via the field attribute, ships size and color variants, and always submits a value (checked or unchecked) thanks to a hidden mirror input.

Usage

The simplest form takes a name and a label:

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

By default the switch submits "true" when on and "false" when off. Both values are always present in the form payload because a hidden input mirrors the field name with the unchecked value:

# on
%{"notifications" => "true"}

# off (hidden input still submits)
%{"notifications" => "false"}

Override the wire values with checked_value and unchecked_value to match the schema the server expects:

<.switch name="active" label="Active" checked_value="1" unchecked_value="0" />

Add sublabel for a short inline qualifier and description for longer explanatory copy rendered beneath the label:

<.switch
  name="auto_save"
  label="Auto save"
  sublabel="Recommended"
  description="Automatically save your changes every few seconds."
/>

Sizes

The size attribute scales the track and thumb together so the switch fits its surrounding context.

<.switch name="compact" label="Compact mode" size="sm" />
<.switch name="default" label="Default" size="md" />
<.switch name="emphasis" label="Important setting" size="lg" />

Colors

The color attribute controls the track color when the switch is on. Use it to reinforce the meaning of the setting being toggled.

<.switch name="backup" label="Automatic backups" color="success" />
<.switch name="beta" label="Beta features" sublabel="Experimental" color="warning" />
<.switch name="public" label="Public profile" color="danger" />

Disabled State

Setting disabled disables the underlying checkbox input and propagates the disabled attribute to the hidden mirror input as well, so the field is omitted from the submitted payload entirely (matching native HTML form behavior). The label, sublabel, and description carry the disabled styling automatically.

<.switch
  name="premium_feature"
  label="Premium feature"
  sublabel="Upgrade required"
  description="This feature is included with the Pro plan."
  disabled
/>

Use disabled to represent toggles that are unavailable due to permissions, subscription tier, or system state, while still showing the user that the option exists.

Form Integration

The component offers two ways to wire form data: the field attribute for Phoenix form bindings, or the name attribute for standalone controls.

Using with Phoenix forms (recommended)

Pass a Phoenix.HTML.FormField to field and the component derives id, name, and the current value automatically. The displayed state is computed by comparing the field's value against checked_value.

<.form :let={f} for={@form} phx-change="validate" phx-submit="save">
  <.switch
    field={f[:notifications_enabled]}
    label="Push notifications"
    description="Receive real-time updates about your account."
  />

  <.switch
    field={f[:dark_mode]}
    label="Dark mode"
    sublabel="Beta"
  />

  <.switch
    field={f[:active]}
    label="Active"
    checked_value="1"
    unchecked_value="0"
  />
</.form>

Using standalone switches

When not bound to a form, supply name, manage checked yourself, and wire interaction through phx-click or any other LiveView binding:

<.switch
  name="theme_toggle"
  label="Dark mode"
  checked={@dark_mode}
  phx-click="toggle_theme"
/>

Checked State Resolution

How the rendered checked attribute is computed depends on which inputs you provide:

The comparison uses Phoenix.HTML.html_escape/1 on both sides, so integers and strings with the same string representation match (for example value={1} against checked_value="1").

Examples

Theme toggle wired to a LiveView event:

<.switch
  name="theme"
  label="Dark mode"
  checked={@dark_mode}
  phx-click="toggle_theme"
/>

Notification preferences panel where each switch toggles a single setting:

<div class="flex flex-col gap-4">
  <.switch
    name="push_notifications"
    label="Push notifications"
    sublabel="Mobile and desktop"
    description="Receive notifications when new activity occurs."
    checked={@settings.push_notifications}
    phx-click="toggle_setting"
    phx-value-setting="push_notifications"
  />

  <.switch
    name="email_notifications"
    label="Email notifications"
    description="Receive email updates about important account activity."
    checked={@settings.email_notifications}
    phx-click="toggle_setting"
    phx-value-setting="email_notifications"
  />

  <.switch
    name="marketing_emails"
    label="Marketing communications"
    sublabel="Optional"
    color="info"
    checked={@settings.marketing_emails}
    phx-click="toggle_setting"
    phx-value-setting="marketing_emails"
  />
</div>

Account settings form bound to a changeset:

<.form :let={f} for={@form} phx-change="validate" phx-submit="save">
  <.switch
    field={f[:two_factor_enabled]}
    label="Two-factor authentication"
    description="Require a verification code in addition to your password."
    color="success"
  />

  <.switch
    field={f[:public_profile]}
    label="Public profile"
    description="Allow other users on the platform to view your profile."
    color="danger"
  />

  <.switch
    field={f[:active]}
    label="Account active"
    checked_value="1"
    unchecked_value="0"
  />

  <.button type="submit">Save changes</.button>
</.form>

Switch rendered outside its associated form by referencing the form id. Useful when the toggle visually belongs to a sidebar, header, or sticky footer that sits outside the <form> element the field submits with:

<form id="signup-form" phx-submit="register">
  <%!-- form fields --%>
</form>

<div class="sticky bottom-0 p-4">
  <.switch name="agree" label="I agree to the terms" form="signup-form" />
  <button type="submit" form="signup-form">Sign up</button>
</div>