04 · Forms — selection

Checkbox

color (7) × state · size xs–lg · shape square/circle · filled · indeterminate · description · disabled

A checkbox with the API axes: color, size, shape, filled, indeterminate, label, description, disabled.

Checking and unchecking

.heex
<div class="flex flex-wrap items-start gap-2.5"><.checkbox color="primary" label="Emitir NF-e" loop /><.checkbox color="neutral" label="Emitir NF-e" loop /><.checkbox color="success" label="Emitir NF-e" loop /><.checkbox color="secondary" label="Emitir NF-e" loop /></div>

color × state

desmarcadomarcadoparcialfilleddesabilitadoneutral
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">desmarcado</span><span class="text-center font-mono text-xs text-muted">marcado</span><span class="text-center font-mono text-xs text-muted">parcial</span><span class="text-center font-mono text-xs text-muted">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"><.checkbox color="neutral" /></div><div class="flex min-w-0 justify-center"><.checkbox color="neutral" checked /></div><div class="flex min-w-0 justify-center"><.checkbox color="neutral" indeterminate id="ind-neutral" /></div><div class="flex min-w-0 justify-center"><.checkbox color="neutral" filled /></div><div class="flex min-w-0 justify-center"><.checkbox color="neutral" disabled checked /></div><span class="font-mono text-xs text-muted">primary</span><div class="flex min-w-0 justify-center"><.checkbox color="primary" /></div><div class="flex min-w-0 justify-center"><.checkbox color="primary" checked /></div><div class="flex min-w-0 justify-center"><.checkbox color="primary" indeterminate id="ind-primary" /></div><div class="flex min-w-0 justify-center"><.checkbox color="primary" filled /></div><div class="flex min-w-0 justify-center"><.checkbox color="primary" disabled checked /></div><span class="font-mono text-xs text-muted">secondary</span><div class="flex min-w-0 justify-center"><.checkbox color="secondary" /></div><div class="flex min-w-0 justify-center"><.checkbox color="secondary" checked /></div><div class="flex min-w-0 justify-center"><.checkbox color="secondary" indeterminate id="ind-secondary" /></div><div class="flex min-w-0 justify-center"><.checkbox color="secondary" filled /></div><div class="flex min-w-0 justify-center"><.checkbox color="secondary" disabled checked /></div><span class="font-mono text-xs text-muted">info</span><div class="flex min-w-0 justify-center"><.checkbox color="info" /></div><div class="flex min-w-0 justify-center"><.checkbox color="info" checked /></div><div class="flex min-w-0 justify-center"><.checkbox color="info" indeterminate id="ind-info" /></div><div class="flex min-w-0 justify-center"><.checkbox color="info" filled /></div><div class="flex min-w-0 justify-center"><.checkbox color="info" disabled checked /></div><span class="font-mono text-xs text-muted">success</span><div class="flex min-w-0 justify-center"><.checkbox color="success" /></div><div class="flex min-w-0 justify-center"><.checkbox color="success" checked /></div><div class="flex min-w-0 justify-center"><.checkbox color="success" indeterminate id="ind-success" /></div><div class="flex min-w-0 justify-center"><.checkbox color="success" filled /></div><div class="flex min-w-0 justify-center"><.checkbox color="success" disabled checked /></div><span class="font-mono text-xs text-muted">warning</span><div class="flex min-w-0 justify-center"><.checkbox color="warning" /></div><div class="flex min-w-0 justify-center"><.checkbox color="warning" checked /></div><div class="flex min-w-0 justify-center"><.checkbox color="warning" indeterminate id="ind-warning" /></div><div class="flex min-w-0 justify-center"><.checkbox color="warning" filled /></div><div class="flex min-w-0 justify-center"><.checkbox color="warning" disabled checked /></div><span class="font-mono text-xs text-muted">error</span><div class="flex min-w-0 justify-center"><.checkbox color="error" /></div><div class="flex min-w-0 justify-center"><.checkbox color="error" checked /></div><div class="flex min-w-0 justify-center"><.checkbox color="error" indeterminate id="ind-error" /></div><div class="flex min-w-0 justify-center"><.checkbox color="error" filled /></div><div class="flex min-w-0 justify-center"><.checkbox color="error" disabled checked /></div></div>

size × shape

xssmmdlgsquare
circle
.heex
<div class="grid grid-cols-[90px_repeat(4,minmax(0,1fr))] items-center gap-x-3 gap-y-2.5"><span></span><span class="text-center font-mono text-xs text-muted">xs</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">square</span><div class="flex min-w-0 justify-center"><.checkbox color="primary" size="xs" shape="square" checked label="Rótulo" /></div><div class="flex min-w-0 justify-center"><.checkbox color="primary" size="sm" shape="square" checked label="Rótulo" /></div><div class="flex min-w-0 justify-center"><.checkbox color="primary" size="md" shape="square" checked label="Rótulo" /></div><div class="flex min-w-0 justify-center"><.checkbox color="primary" size="lg" shape="square" checked label="Rótulo" /></div><span class="font-mono text-xs text-muted">circle</span><div class="flex min-w-0 justify-center"><.checkbox color="primary" size="xs" shape="circle" checked label="Rótulo" /></div><div class="flex min-w-0 justify-center"><.checkbox color="primary" size="sm" shape="circle" checked label="Rótulo" /></div><div class="flex min-w-0 justify-center"><.checkbox color="primary" size="md" shape="circle" checked label="Rótulo" /></div><div class="flex min-w-0 justify-center"><.checkbox color="primary" size="lg" shape="circle" checked label="Rótulo" /></div></div>

with a description

.heex
<div class="flex flex-col gap-3"><.checkbox color="primary" checked label="Enviar DANFE por e-mail" description="O cliente recebe o PDF e o XML assim que a nota é autorizada." /><.checkbox color="primary" label="Reter ISS" description="Só para serviços com retenção na fonte." /><.checkbox color="primary" indeterminate id="ind-all" label="Selecionar todos" description="3 de 8 pedidos marcados" /></div>

API values that complete the parity

variant=basic
variant=outline
variant=card
variant=chip
.heex
<div class="grid grid-cols-4 gap-3.5">
  <div class="flex flex-col items-start gap-1.5"><.checkbox color="primary" checked label="Emitir" /><span class="font-mono text-[11px] text-muted">variant=basic</span></div>
  <div class="flex flex-col items-start gap-1.5"><.checkbox color="primary" variant="outline" checked label="Emitir" /><span class="font-mono text-[11px] text-muted">variant=outline</span></div>
  <div class="flex flex-col items-start gap-1.5"><.checkbox_group id="cb05-card" variant="card" color="primary" class="w-[220px]" value={["nfe"]} options={[%{label: "Emitir NF-e", value: "nfe", description: "Ao confirmar"}]} /><span class="font-mono text-[11px] text-muted">variant=card</span></div>
  <div class="flex flex-col items-start gap-1.5"><.checkbox_group id="cb05-chip" variant="chip" color="primary" value={["emitir"]} options={[%{label: "Emitir", value: "emitir"}]} /><span class="font-mono text-[11px] text-muted">variant=chip</span></div>
</div>

Usage

<.checkbox field={@form[:terms]} label="Aceito os termos" />
<.checkbox field={@form[:all]} indeterminate color="primary" />
<.checkbox name="x" shape="circle" size="lg" filled description="Envia uma cópia por e-mail" />

Rules

  • Checking: a background in the color + a white tick, 120ms.
  • indeterminate draws the dash of a partial selection.
  • filled gives a light background while unchecked.

API reference

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

checkbox/1 (the box with label and description) and checkbox_group/1 (one checkbox per option of a list field).

<.checkbox name="terms" label="I agree" />
<.checkbox field={@form[:remember]} label="Remember me" color="primary" />
<.checkbox name="pro" label="Pro plan" description="Billed yearly" color="primary" checked />
<.checkbox name="all" label="Select all (3 of 8)" indeterminate />

<.checkbox_group field={@form[:roles]} label="Roles"
  options={[{"Admin", "admin"}, {"Editor", "editor"}]} />
<.checkbox_group field={@form[:channels]} variant="chip" color="primary" options={[
  %{label: "E-mail", value: "email", count: 3}, %{label: "WhatsApp", value: "whatsapp"}]} />

Inside a form a named checkbox sends unchecked_value through a hidden input when it is off (hidden_input={false} skips it), so the field is always in the params. indeterminate draws the dash of a partial selection (data-ind); the indeterminate property and aria-checked="mixed" are set by the LedgerUI.Indeterminate hook (priv/static/ledger_ui/hooks/indeterminate.js), so the box needs an id: it is taken from id, the field, the name or the label. Pass false when the box can leave that state; a click clears the dash.

Extra HTML attributes (form, required, phx-click, data-*...) go to the <input>.

<.checkbox>

Attr Type Default Values / notes
field {:struct, Phoenix.HTML.FormField} nil
id :string nil
name :string nil
value :any nil
checked :boolean nil
indeterminate :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 "square" square, circle
size :string "md" nil, xs, sm, md, lg
label :string nil
label_class :any nil
description :string nil
errors :list []
disabled :boolean false
loop :boolean false Demo animation (CSS only): the box fills and the tick draws by itself.
wrapper_class :any nil Classes of the block that wraps box and errors.
class :any nil Classes of the label (the clickable row).
style :string nil Inline style of the label, not of the input.

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

Slots:

  • <:inner_block>

<.checkbox_group>

Attr Type Default Values / notes
field {:struct, Phoenix.HTML.FormField} nil
id :string nil
name :string nil
value :any nil
options :list []
color :string "neutral" neutral, primary, secondary, info, success, warning, error
variant :string "basic" basic, outline, card, chip
filled :boolean false
shape :string "square" square, circle
size :string "md" xs, sm, md, lg
label :string nil
label_class :any nil
help :string nil
errors :list []
disabled :boolean false
wrapper_class :any nil
class :any nil

Any other HTML/phx attribute goes to the root element.

Slots:

  • <:checkbox> - attrs: value, label, color, disabled, description, count, icon