Documentation Playground
Skip to content
Docs

Checkbox Group

Set of interactive buttons where multiple options can be selected at a time. 
<.checkbox_group default_value={["1"]} name="checkbox-group-hero">
  <:item value="1">Fun</:item>
  <:item value="2">Serious</:item>
  <:item value="3">Smart</:item>
</.checkbox_group>

API Reference

This component is based on the div element and supports common margin props.

Root

Contains all the parts of a checkbox group.

Prop Type Default Description
class string nil
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_value list []
disabled boolean false
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
on_value_change string nil
orientation string "vertical"
required boolean false
size string "2"
style string ""
value list nil
variant string "surface"
class
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_value
Type list Default []
disabled
Type boolean Default false
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
Type string Default nil
on_value_change
Type string Default nil
orientation
Type string Default "vertical"
required
Type boolean Default false
size
Type string Default "2"
style
Type string Default ""
value
Type list Default nil
variant
Type string Default "surface"

Slot convenience (same props, maps <:item> into root + items):

Prop Type Default Description
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_value list [] Initial selected values.
disabled boolean false Whether the entire checkbox group is disabled.
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 — Form name attribute for the checkbox group.
on_value_change string nil
required boolean false
size string "2" Checkbox button size from 1 to 3. Controls overall dimensions and indicator size.
style string ""
value list nil Controlled selected values.
variant string "surface" Visual style variant. One of 'surface', 'classic', or 'soft'.
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_value Initial selected values.
Type list Default []
disabled Whether the entire checkbox group is disabled.
Type boolean Default false
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 for the checkbox group.
Type string Default —
on_value_change
Type string Default nil
required
Type boolean Default false
size Checkbox button size from 1 to 3. Controls overall dimensions and indicator size.
Type string Default "2"
style
Type string Default ""
value Controlled selected values.
Type list Default nil
variant Visual style variant. One of 'surface', 'classic', or 'soft'.
Type string Default "surface"

Item

An item in the group that can be checked.

Prop Type Default Description
checked boolean false
class string nil
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.
disabled boolean false
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'}`
size string "2"
style string ""
value string —
variant string "surface"
checked
Type boolean Default false
class
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 —
disabled
Type boolean Default false
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 —
size
Type string Default "2"
style
Type string Default ""
value
Type string Default —
variant
Type string Default "surface" 
<.checkbox_group_root id="traits" name="traits" default_value={["1"]}>
  <.checkbox_group_item value="1" checked>Fun</.checkbox_group_item>
  <.checkbox_group_item value="2" disabled>Serious</.checkbox_group_item>
</.checkbox_group_root>

Or with slots:

<.checkbox_group name="traits" default_value={["1"]}>
  <:item value="1">Fun</:item>
  <:item value="2" disabled>Serious</:item>
</.checkbox_group>

Examples

Size

Use the size prop to control the checkbox size.

<.flex align="center" gap="2">
  <.checkbox_group size="1" default_value={["1"]} name="cg-size-1">
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group size="2" default_value={["2"]} name="cg-size-2">
    <:item value="2"></:item>
  </.checkbox_group>
  <.checkbox_group size="3" default_value={["3"]} name="cg-size-3">
    <:item value="3"></:item>
  </.checkbox_group>
</.flex>

Variant

Use the variant prop to control the visual style of the checkboxes.

<.flex gap="2">
  <.checkbox_group variant="surface" default_value={["1"]} name="cg-variant-surface">
    <:item value="1"></:item>
    <:item value="2"></:item>
  </.checkbox_group>
  <.checkbox_group variant="classic" default_value={["1"]} name="cg-variant-classic">
    <:item value="1"></:item>
    <:item value="2"></:item>
  </.checkbox_group>
  <.checkbox_group variant="soft" default_value={["1"]} name="cg-variant-soft">
    <:item value="1"></:item>
    <:item value="2"></:item>
  </.checkbox_group>
</.flex>

Color

Use the color prop to assign a specific accent color.

<.flex gap="2">
  <.checkbox_group color="indigo" default_value={["1"]} name="cg-color-indigo">
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group color="cyan" default_value={["1"]} name="cg-color-cyan">
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group color="orange" default_value={["1"]} name="cg-color-orange">
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group color="crimson" default_value={["1"]} name="cg-color-crimson">
    <:item value="1"></:item>
  </.checkbox_group>
</.flex>

High-contrast

Use the high_contrast prop to increase color contrast with the background.

<.grid rows="2" gap="2" display="inline-grid" flow="column">
  <.checkbox_group color="indigo" default_value={["1"]} name="cg-hc-indigo">
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group color="indigo" default_value={["1"]} high_contrast name="cg-hc-indigo-contrast">
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group color="cyan" default_value={["1"]} name="cg-hc-cyan">
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group color="cyan" default_value={["1"]} high_contrast name="cg-hc-cyan-contrast">
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group color="orange" default_value={["1"]} name="cg-hc-orange">
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group color="orange" default_value={["1"]} high_contrast name="cg-hc-orange-contrast">
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group color="crimson" default_value={["1"]} name="cg-hc-crimson">
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group
    color="crimson"
    default_value={["1"]}
    high_contrast
    name="cg-hc-crimson-contrast"
  >
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group color="gray" default_value={["1"]} name="cg-hc-gray">
    <:item value="1"></:item>
  </.checkbox_group>
  <.checkbox_group color="gray" default_value={["1"]} high_contrast name="cg-hc-gray-contrast">
    <:item value="1"></:item>
  </.checkbox_group>
</.grid>

Disabled

Use the native disabled attribute to create a disabled checkbox.

<.flex direction="column" gap="2">
  <.checkbox_group default_value={["2"]} name="cg-disabled-enabled">
    <:item value="1">Off</:item>
    <:item value="2">On</:item>
  </.checkbox_group>
  <.checkbox_group default_value={["2"]} name="cg-disabled-items">
    <:item value="1" disabled>Off</:item>
    <:item value="2" disabled>On</:item>
  </.checkbox_group>
</.flex>
← Checkbox Cards Context Menu →