04 · Formulários — seleção

Switch

color (7) × on/off · size sm/md/lg · shape squircle/pill · thumb_inset 2–6 · variant basic/outline · filled · label_position · description · disabled

Liga/desliga de efeito imediato. Padrão do kit: trilho com cantos arredondados (squircle); pill só como opção.

Ligando e desligando

.heex
<div class="flex flex-wrap items-center gap-2.5"><.switch color="primary" label="Emissão automática" loop /><.switch color="success" label="Backup diário" loop /><.switch color="neutral" label="Modo escuro" loop /><.switch color="primary" label="Contorno" variant="outline" loop /></div>

color × estado

offonoutline onoutline filleddesabilitadoneutral
primary
secondary
info
success
warning
error
.heex
<div class="grid grid-cols-[100px_repeat(5,minmax(0,1fr))] items-center gap-x-3 gap-y-2.5"><span></span><span class="text-center font-mono text-xs text-muted">off</span><span class="text-center font-mono text-xs text-muted">on</span><span class="text-center font-mono text-xs text-muted">outline on</span><span class="text-center font-mono text-xs text-muted">outline filled</span><span class="text-center font-mono text-xs text-muted">desabilitado</span><span class="font-mono text-xs text-muted">neutral</span><div class="flex min-w-0 justify-center"><.switch color="neutral" /></div><div class="flex min-w-0 justify-center"><.switch color="neutral" checked /></div><div class="flex min-w-0 justify-center"><.switch color="neutral" variant="outline" checked /></div><div class="flex min-w-0 justify-center"><.switch color="neutral" variant="outline" filled checked /></div><div class="flex min-w-0 justify-center"><.switch color="neutral" disabled checked /></div><span class="font-mono text-xs text-muted">primary</span><div class="flex min-w-0 justify-center"><.switch color="primary" /></div><div class="flex min-w-0 justify-center"><.switch color="primary" checked /></div><div class="flex min-w-0 justify-center"><.switch color="primary" variant="outline" checked /></div><div class="flex min-w-0 justify-center"><.switch color="primary" variant="outline" filled checked /></div><div class="flex min-w-0 justify-center"><.switch color="primary" disabled checked /></div><span class="font-mono text-xs text-muted">secondary</span><div class="flex min-w-0 justify-center"><.switch color="secondary" /></div><div class="flex min-w-0 justify-center"><.switch color="secondary" checked /></div><div class="flex min-w-0 justify-center"><.switch color="secondary" variant="outline" checked /></div><div class="flex min-w-0 justify-center"><.switch color="secondary" variant="outline" filled checked /></div><div class="flex min-w-0 justify-center"><.switch color="secondary" disabled checked /></div><span class="font-mono text-xs text-muted">info</span><div class="flex min-w-0 justify-center"><.switch color="info" /></div><div class="flex min-w-0 justify-center"><.switch color="info" checked /></div><div class="flex min-w-0 justify-center"><.switch color="info" variant="outline" checked /></div><div class="flex min-w-0 justify-center"><.switch color="info" variant="outline" filled checked /></div><div class="flex min-w-0 justify-center"><.switch color="info" disabled checked /></div><span class="font-mono text-xs text-muted">success</span><div class="flex min-w-0 justify-center"><.switch color="success" /></div><div class="flex min-w-0 justify-center"><.switch color="success" checked /></div><div class="flex min-w-0 justify-center"><.switch color="success" variant="outline" checked /></div><div class="flex min-w-0 justify-center"><.switch color="success" variant="outline" filled checked /></div><div class="flex min-w-0 justify-center"><.switch color="success" disabled checked /></div><span class="font-mono text-xs text-muted">warning</span><div class="flex min-w-0 justify-center"><.switch color="warning" /></div><div class="flex min-w-0 justify-center"><.switch color="warning" checked /></div><div class="flex min-w-0 justify-center"><.switch color="warning" variant="outline" checked /></div><div class="flex min-w-0 justify-center"><.switch color="warning" variant="outline" filled checked /></div><div class="flex min-w-0 justify-center"><.switch color="warning" disabled checked /></div><span class="font-mono text-xs text-muted">error</span><div class="flex min-w-0 justify-center"><.switch color="error" /></div><div class="flex min-w-0 justify-center"><.switch color="error" checked /></div><div class="flex min-w-0 justify-center"><.switch color="error" variant="outline" checked /></div><div class="flex min-w-0 justify-center"><.switch color="error" variant="outline" filled checked /></div><div class="flex min-w-0 justify-center"><.switch color="error" disabled checked /></div></div>

size × shape

smmdlgsquircle (padrão)
pill
.heex
<div class="grid grid-cols-[130px_repeat(3,minmax(0,1fr))] items-center gap-x-3 gap-y-2.5"><span></span><span class="text-center font-mono text-xs text-muted">sm</span><span class="text-center font-mono text-xs text-muted">md</span><span class="text-center font-mono text-xs text-muted">lg</span><span class="font-mono text-xs text-muted">squircle (padrão)</span><div class="flex min-w-0 justify-center"><div class="flex flex-wrap items-center gap-2.5"><.switch color="primary" size="sm" shape="squircle" /><.switch color="primary" size="sm" shape="squircle" checked /></div></div><div class="flex min-w-0 justify-center"><div class="flex flex-wrap items-center gap-2.5"><.switch color="primary" size="md" shape="squircle" /><.switch color="primary" size="md" shape="squircle" checked /></div></div><div class="flex min-w-0 justify-center"><div class="flex flex-wrap items-center gap-2.5"><.switch color="primary" size="lg" shape="squircle" /><.switch color="primary" size="lg" shape="squircle" checked /></div></div><span class="font-mono text-xs text-muted">pill</span><div class="flex min-w-0 justify-center"><div class="flex flex-wrap items-center gap-2.5"><.switch color="primary" size="sm" shape="pill" /><.switch color="primary" size="sm" shape="pill" checked /></div></div><div class="flex min-w-0 justify-center"><div class="flex flex-wrap items-center gap-2.5"><.switch color="primary" size="md" shape="pill" /><.switch color="primary" size="md" shape="pill" checked /></div></div><div class="flex min-w-0 justify-center"><div class="flex flex-wrap items-center gap-2.5"><.switch color="primary" size="lg" shape="pill" /><.switch color="primary" size="lg" shape="pill" checked /></div></div></div>

thumb_inset

2
3
4
5
6
.heex
<div class="flex flex-wrap items-center gap-2.5"><div class="flex flex-col gap-1.5"><.switch color="primary" size="lg" thumb_inset={2} checked /><span class="font-mono text-xs text-muted">2</span></div><div class="flex flex-col gap-1.5"><.switch color="primary" size="lg" thumb_inset={3} checked /><span class="font-mono text-xs text-muted">3</span></div><div class="flex flex-col gap-1.5"><.switch color="primary" size="lg" thumb_inset={4} checked /><span class="font-mono text-xs text-muted">4</span></div><div class="flex flex-col gap-1.5"><.switch color="primary" size="lg" thumb_inset={5} checked /><span class="font-mono text-xs text-muted">5</span></div><div class="flex flex-col gap-1.5"><.switch color="primary" size="lg" thumb_inset={6} checked /><span class="font-mono text-xs text-muted">6</span></div></div>

label_position · description

.heex
<div class="grid grid-cols-2 gap-4"><.switch color="primary" checked label="Notificar no WhatsApp" description="Mensagem quando a nota for autorizada" /><.switch color="primary" label_position="left" label="Cobrança automática" description="Rótulo à esquerda" /></div>

Valores da API que completam a paridade

label_position=right
.heex
<div class="grid grid-cols-3 gap-3.5"><div class="flex flex-col items-start gap-1.5"><.switch color="primary" checked label="Ativo" /><span class="font-mono text-[11px] text-muted">label_position=right</span></div></div>

Uso

<.switch field={@form[:active]} label="Ativo" />
<.switch name="auto" color="success" size="lg" thumb_inset={4} />
<.switch name="x" variant="outline" filled label_position="left" description="Notificar no WhatsApp" />

Regras

  • O botão desliza em 180ms; o trilho troca de cor junto.
  • thumb_inset afasta o botão da borda: quanto maior, menor o botão.
  • Use para efeito imediato; para escolha que só vale ao salvar, use checkbox.

Referência da API

Todos os function components, atributos, valores e slots que este componente cobre.

A switch: a checkbox drawn as a track and thumb, for an effect that is immediate.

<.switch name="notify" label="Notifications" color="primary" />
<.switch field={@form[:public]} label="Public" variant="outline" color="success" filled />
<.switch name="dense" size="sm" shape="pill" thumb_inset={4} checked />
<.switch name="email" label="Email" label_position="left" wrapper_class="w-full justify-between" />

With a name (or field) the switch holds a real, visually hidden checkbox (so the form, the keyboard and phx-change work) and, like checkbox/1, sends unchecked_value through a hidden input when off. The track and aria-checked flip in the browser with Phoenix.LiveView.JS, no round trip (aria-checked draws the on look); without a name the label itself is the click target.

shape is squircle (the default look) or pill. thumb_inset (2..6 px) puts the thumb away from the edge: the higher, the smaller it is; left nil it is 3px. Extra HTML attributes go to the <input> (or to the label when there is no name).

<.switch>

Attr Type Default Values / notes
field {:struct, Phoenix.HTML.FormField} nil
id :string nil
name :string nil
value :any nil
checked :boolean nil
checked_value :string "true"
unchecked_value :string "false"
hidden_input :boolean true
color :string "neutral" neutral, primary, secondary, info, success, warning, error
variant :string "basic" basic, outline
filled :boolean false
shape :string "squircle" pill, squircle
size :string "md" sm, md, lg
thumb_inset :integer nil nil, 2, 3, 4, 5, 6
label :string nil
label_position :string "right" right, left
label_class :any nil
description :string nil
errors :list []
disabled :boolean false
loop :boolean false Demo animation (CSS only): the switch turns on and off by itself.
wrapper_class :any nil
class :any nil

Any other HTML/phx attribute goes to the root element, including form, required.

Slots:

  • <:inner_block>