Checkbox
Lets people turn an option on or off as part of a form they confirm separately.
Default
<.checkbox id="checkbox-unchecked" label="Unchecked" />
<.checkbox id="checkbox-checked" label="Checked" checked />
Indeterminate
<.checkbox id="checkbox-indeterminate" label="Indeterminate" indeterminate />
Disabled
<.checkbox id="checkbox-disabled" label="Disabled" disabled />
<.checkbox id="checkbox-disabled-checked" label="Disabled checked" checked disabled />
<.checkbox
id="checkbox-disabled-indeterminate"
label="Disabled indeterminate"
indeterminate
disabled
/>
With description
A second line explains what the option changes.
<.checkbox
id="checkbox-description-flaky"
label="Mark flaky tests"
description="Tests that pass and fail on the same commit are flagged in test insights."
/>
<.checkbox
id="checkbox-description-slack"
label="Post build summaries to Slack"
description="A summary is sent to the project's channel after every build on the default branch."
/>
Guidelines
-
Write the
labelas the option itself, such as Keep me logged in, so checking the box reads as agreeing to it. - Write a label that acknowledges something as a full sentence, such as I agree to the Terms of Service.
-
Use
descriptionfor the consequence of the option rather than restating the label. -
Use
indeterminateon a checkbox that controls a group when only some of the group is checked. It's a visual state, not a third value: set it from the group, and clear it once the group is all checked or all unchecked. -
Wrap related checkboxes in a
fieldsetwith alegendnaming the group, such as Notifications. -
Pass
fieldto take the id, name, and value from a form field. Addmultiplewhen several checkboxes share one field, so the name ends in[]. - For a setting that applies as soon as it changes, use a toggle instead. A checkbox suits choices confirmed with a separate action, such as a submit button.
API reference
<.checkbox>
| Attribute | Type | Default | Description |
|---|---|---|---|
|
checked
|
boolean
|
–
|
Whether the checkbox is checked.
|
|
description
|
string
|
nil
|
An optional description.
|
|
disabled
|
boolean
|
false
|
Whether the checkbox is disabled.
|
|
field
|
Phoenix.HTML.FormField
|
nil
|
A Phoenix form field.
|
|
id
|
string
|
nil
|
The id of the checkbox.
|
|
indeterminate
|
boolean
|
false
|
Whether the checkbox is indeterminate.
|
|
label
Required
|
string
|
–
|
The label of the checkbox.
|
|
multiple
|
boolean
|
false
|
Whether the checkbox is part of a multiple checkbox group.
|
|
name
|
string
|
–
|
The name of the checkbox.
|
|
tabindex
|
integer
|
nil
|
Tabindex to add to the checkbox control
|
|
value
|
any
|
–
|
The value used to derive the checked state.
|
Also accepts global attributes.