Headless Checkbox Group

Overview of the Phoenix and LiveView Headless Checkbox Group Component

The Mishka Chelekom Headless Checkbox Group ships zero opinionated styling - only the semantic markup, full WAI-ARIA wiring, and paired-presence state (data-checked/data-unchecked/data-indeterminate). Each item is a role="checkbox" button with a hidden native checkbox for form submission as name[], and an optional select_all slot renders a tristate parent that reflects and toggles every child. Every part - label, item, and indicator - is addressable through a *_class attribute, so you style it entirely with your own Tailwind classes while the accessibility and behavior keep working underneath.

**Headless = bring your own design.** The example below is a faithful port of Base UI's own Checkbox Group demo. Copy it, then swap the classes for your design system - the behavior never changes.

Base UI Checkbox Group example (Phoenix headless)

Apples

<.checkbox_group
  id="checkbox-group-hero"
  class="flex flex-col items-start gap-1 text-neutral-950 dark:text-white"
  label_class="text-sm font-bold"
>
  <:indicator_icon>
    <svg
      width="16"
      height="16"
      viewBox="0 0 16 16"
      fill="none"
      stroke="currentColor"
      class="block group-data-[unchecked]/box:hidden"
      style="display: block"
    >
      <path d="m2.5 8.5 4 4 7-9" />
    </svg>
  </:indicator_icon>

  <:label>Apples</:label>

  <:item
    value="fuji-apple"
    checked
    item_class="group flex items-center gap-2 text-sm font-normal text-neutral-950 dark:text-white"
    indicator_class="group/box flex size-4 shrink-0 items-center justify-center border rounded-none p-0 border-neutral-950 bg-white text-white dark:border-white dark:bg-neutral-950 dark:text-neutral-950 data-[checked]:bg-neutral-950 data-[checked]:text-white dark:data-[checked]:bg-white dark:data-[checked]:text-neutral-950 group-focus-visible:outline-2 group-focus-visible:outline-offset-2 group-focus-visible:outline-neutral-950 dark:group-focus-visible:outline-white"
  >
    Fuji
  </:item>

  <:item
    value="gala-apple"
    item_class="group flex items-center gap-2 text-sm font-normal text-neutral-950 dark:text-white"
    indicator_class="group/box flex size-4 shrink-0 items-center justify-center border rounded-none p-0 border-neutral-950 bg-white text-white dark:border-white dark:bg-neutral-950 dark:text-neutral-950 data-[checked]:bg-neutral-950 data-[checked]:text-white dark:data-[checked]:bg-white dark:data-[checked]:text-neutral-950 group-focus-visible:outline-2 group-focus-visible:outline-offset-2 group-focus-visible:outline-neutral-950 dark:group-focus-visible:outline-white"
  >
    Gala
  </:item>

  <:item
    value="granny-smith-apple"
    item_class="group flex items-center gap-2 text-sm font-normal text-neutral-950 dark:text-white"
    indicator_class="group/box flex size-4 shrink-0 items-center justify-center border rounded-none p-0 border-neutral-950 bg-white text-white dark:border-white dark:bg-neutral-950 dark:text-neutral-950 data-[checked]:bg-neutral-950 data-[checked]:text-white dark:data-[checked]:bg-white dark:data-[checked]:text-neutral-950 group-focus-visible:outline-2 group-focus-visible:outline-offset-2 group-focus-visible:outline-neutral-950 dark:group-focus-visible:outline-white"
  >
    Granny Smith
  </:item>
</.checkbox_group>

Parts & data attributes

Each part carries a stable data-part and a structural chelekom-checkbox_group__* class you can target, plus paired-presence state for checked/unchecked/indeterminate transitions.

Part	data-part	State / ARIA	Purpose
Root	-	role="group", aria-labelledby, data-disabled	The wrapping group container.
Label	label	-	Visible group label wired to aria-labelledby.
Item	item	role="checkbox", aria-checked, data-checked, data-unchecked, data-indeterminate, data-disabled, data-parent	A single checkbox option; a select_all item carries data-parent (the tristate "select all").
Indicator	indicator	aria-hidden, data-checked, data-unchecked, data-indeterminate	The visual box that renders the indicator icon.
Input	input	-	Hidden native checkbox; submits as name[].

Accessibility

Follows the WAI-ARIA Checkbox pattern : pressing Space or Enter toggles the focused checkbox, Tab moves between checkboxes, and toggling the select_all parent checks or unchecks every item. The parent reports its tristate state via aria-checked="mixed" when only some items are checked.

Name	Type	Required	Description
id	string	Yes	Unique id; anchors the group label + item ids.
name	string	No	Base form name; items submit as name[].
disabled	boolean	No	Disable the whole group (cascades to every item).
on_change	string	No	LiveView event pushed with the selected values (payload carries the value list).
class	any	No	Extra classes for the root.
label_class	any	No	Extra classes for the group label.
indicator_icon	slot	No	Shared icon rendered inside every item's indicator box.
label	slot	No	Accessible group label (wired to aria-labelledby).
select_all	slot	No	Optional tristate "select all" parent (reflects and toggles all items); accepts item_class and indicator_class.
item	slot	Yes	A checkbox option; accepts value (required), checked, disabled, item_class and indicator_class.

Name	Type	Options	Recommended?
`--type`	string	checkbox_group	Yes
`--only`	string	checkbox_group	Yes
`--module`	string	Something	NO

Mishka

Overview of the Phoenix and LiveView Headless Checkbox Group Component

Base UI Checkbox Group example (Phoenix headless)

Parts & data attributes

Accessibility

Headless Checkbox Group component props

CheckboxGroup CLI Arguments