LanternUI.Components.Switch (LanternUI v0.9.0)

Copy Markdown View Source

Toggle switch for binary settings. Mirrors Fluxon's switch/1 surface.

<.switch field={@form[:notifications]} label="Enable notifications" />
<.switch name="dark" checked={@dark} label="Dark mode" size="sm" color="accent" />

A hidden input always submits unchecked_value so forms receive a param even when the switch is off.

The toggle is Zag-driven (a @zag-js/switch state machine, loaded on demand): the hook root carries data-zag plus data-scope="switch" / data-part anatomy, and Zag owns checked state, keyboard, and ARIA while the native inputs stay the form surface. Styling stays lui-* tokens. Two modes:

  • client (default) — Zag owns the value from the initial checked.
  • server-driven (controlled) — the server value (checked) is truth; toggles flow out through on_change, patches flow in.

Summary

Functions

switch(assigns)

Functions

switch(assigns)

Attributes

  • id (:any) - Element id; derived from field when omitted. Defaults to nil.
  • name (:string) - Form input name; derived from field when omitted. Defaults to nil.
  • value (:any) - Current value used to derive checked state. Defaults to nil.
  • checked (:boolean) - Force on/off; else compares value to checked_value. Defaults to nil.
  • checked_value (:any) - Value submitted when the switch is on. Defaults to "true".
  • unchecked_value (:any) - Hidden input value submitted when off. Defaults to "false".
  • label (:string) - Primary label text beside the switch. Defaults to nil.
  • sublabel (:string) - Secondary label line under the primary label. Defaults to nil.
  • description (:string) - Helper text under the label stack. Defaults to nil.
  • errors (:list) - Validation messages; derived from field when used. Defaults to [].
  • size (:string) - Track and thumb size. Defaults to "md". Must be one of "sm", "md", or "lg".
  • color (:string) - On-state track color token. Defaults to "accent".
  • class (:any) - Extra classes merged onto the root element. Defaults to nil.
  • field (Phoenix.HTML.FormField) - Form field; derives id, name, value, and errors. Defaults to nil.
  • disabled (:boolean) - Render disabled and non-interactive. Defaults to false.
  • controlled (:boolean) - Server-driven checked state: checked is truth, patches flow into the machine. Defaults to false.
  • on_change (:string) - Server event pushed on toggle (lantern:switch:set-checked replies). Defaults to nil.
  • on_change_client (:string) - Bubbling DOM CustomEvent dispatched on toggle. Defaults to nil.
  • Global attributes are accepted. Arbitrary HTML/phx-* attributes passed through. Supports all globals plus: ["form", "phx-change", "phx-target", "phx-click"].