<.text as="label" size="2">
<.flex gap="2"><.checkbox default_checked />Agree to Terms and Conditions</.flex>
</.text>API Reference
This component wraps the Checkbox primitive and supports common margin props.
| Prop | Type | Default | Description |
|---|---|---|---|
checked
|
any
|
nil
|
Controlled checked state. Can be true, false, or 'indeterminate'. |
class
|
string
|
nil
|
Additional CSS classes to add to the element. |
color
|
string
|
—
|
Color utility class string. One of: gray, gold, bronze, brown, yellow, amber, orange, tomato, red, ruby, crimson, pink, plum, purple, violet, iris, indigo, blue, cyan, teal, jade, green, grass, lime, mint, sky. |
default_checked
|
any
|
false
|
Initial checked state. If true, checkbox starts checked. |
disabled
|
boolean
|
false
|
Whether the checkbox is disabled. |
form
|
string
|
nil
|
The form ID this checkbox belongs to. |
high_contrast
|
boolean
|
—
|
Whether to increase color contrast with the background. |
id
|
string
|
nil
|
|
m
|
any
|
—
|
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}` |
mb
|
any
|
—
|
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}` |
ml
|
any
|
—
|
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}` |
mr
|
any
|
—
|
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}` |
mt
|
any
|
—
|
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}` |
mx
|
any
|
—
|
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}` |
my
|
any
|
—
|
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}` |
name
|
string
|
nil
|
Form name attribute. |
on_checked_change
|
string
|
nil
|
LiveView event to push when the checked state changes. |
required
|
boolean
|
false
|
Whether the checkbox is required. |
size
|
string
|
"2"
|
Checkbox size from 1 to 3. Controls overall dimensions and indicator size. |
style
|
string
|
""
|
|
value
|
string
|
nil
|
Form value attribute. |
variant
|
string
|
"surface"
|
Visual style variant. One of 'surface', 'classic', or 'soft'. |
checked
Controlled checked state. Can be true, false, or 'indeterminate'.
Type
any
Default
nil
class
Additional CSS classes to add to the element.
Type
string
Default
nil
color
Color utility class string. One of: gray, gold, bronze, brown, yellow, amber, orange, tomato, red, ruby, crimson, pink, plum, purple, violet, iris, indigo, blue, cyan, teal, jade, green, grass, lime, mint, sky.
Type
string
Default
—
default_checked
Initial checked state. If true, checkbox starts checked.
Type
any
Default
false
disabled
Whether the checkbox is disabled.
Type
boolean
Default
false
form
The form ID this checkbox belongs to.
Type
string
Default
nil
high_contrast
Whether to increase color contrast with the background.
Type
boolean
Default
—
id
Type
string
Default
nil
m
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type
any
Default
—
mb
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type
any
Default
—
ml
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type
any
Default
—
mr
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type
any
Default
—
mt
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type
any
Default
—
mx
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type
any
Default
—
my
Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
Type
any
Default
—
name
Form name attribute.
Type
string
Default
nil
on_checked_change
LiveView event to push when the checked state changes.
Type
string
Default
nil
required
Whether the checkbox is required.
Type
boolean
Default
false
size
Checkbox size from 1 to 3. Controls overall dimensions and indicator size.
Type
string
Default
"2"
style
Type
string
Default
""
value
Form value attribute.
Type
string
Default
nil
variant
Visual style variant. One of 'surface', 'classic', or 'soft'.
Type
string
Default
"surface"
Examples
Size
Use the size prop to control the size of the checkbox.
<.flex align="center" gap="2">
<.checkbox size="1" default_checked /><.checkbox size="2" default_checked /><.checkbox
size="3"
default_checked
/>
</.flex>Variant
Use the variant prop to control the visual style of the checkbox.
<.flex align="center" gap="4">
<.flex gap="2">
<.checkbox variant="surface" default_checked /><.checkbox variant="surface" />
</.flex>
<.flex gap="2">
<.checkbox variant="classic" default_checked /><.checkbox variant="classic" />
</.flex>
<.flex gap="2"><.checkbox variant="soft" default_checked /><.checkbox variant="soft" /></.flex>
</.flex>Color
Use the color prop to assign a specific accent color.
<.flex gap="2">
<.checkbox color="indigo" default_checked /><.checkbox color="cyan" default_checked /><.checkbox
color="orange"
default_checked
/><.checkbox color="crimson" default_checked />
</.flex>High-contrast
Use the high_contrast prop to increase color contrast with the background.
<.grid columns="5" display="inline-grid" gap="2">
<.checkbox color="indigo" default_checked /><.checkbox color="cyan" default_checked /><.checkbox
color="orange"
default_checked
/><.checkbox color="crimson" default_checked /><.checkbox color="gray" default_checked /><.checkbox
color="indigo"
default_checked
high_contrast
/><.checkbox color="cyan" default_checked high_contrast /><.checkbox
color="orange"
default_checked
high_contrast
/><.checkbox color="crimson" default_checked high_contrast /><.checkbox
color="gray"
default_checked
high_contrast
/>
</.grid>Alignment
Composing checkbox within text automatically centers it with the first line of text.
<.flex direction="column" gap="3">
<.text as="label" size="2">
<.flex gap="2"><.checkbox size="1" default_checked /> Agree to Terms and Conditions</.flex>
</.text>
<.text as="label" size="3">
<.flex gap="2"><.checkbox size="2" default_checked /> Agree to Terms and Conditions</.flex>
</.text>
<.text as="label" size="4">
<.flex gap="2"><.checkbox size="3" default_checked /> Agree to Terms and Conditions</.flex>
</.text>
</.flex>It is automatically well-aligned with multi-line text too.
<.box max_width="300px">
<.text as="label" size="3">
<.flex gap="2">
<.checkbox default_checked />
I understand that these documents are confidential and cannot be shared with a third party.
</.flex>
</.text>
</.box>Disabled
Use the native disabled attribute to create a disabled checkbox.
<.flex direction="column" gap="2">
<.text as="label" size="2">
<.flex gap="2"><.checkbox /> Not checked</.flex>
</.text>
<.text as="label" size="2">
<.flex gap="2"><.checkbox default_checked /> Checked</.flex>
</.text>
<.text as="label" size="2" color="gray">
<.flex gap="2"><.checkbox disabled /> Not checked</.flex>
</.text>
<.text as="label" size="2" color="gray">
<.flex gap="2"><.checkbox disabled default_checked /> Checked</.flex>
</.text>
</.flex>Indeterminate
Use the "indeterminate" value to create an indeterminate checkbox.
<.flex gap="2">
<.checkbox default_checked="indeterminate" /><.checkbox checked="indeterminate" />
</.flex>