CheckboxGroup

A fieldset of Checkbox controls with one legend, hint and error.

Last updated

Notify me about

Pick as many as you like.

Show code
<CheckboxGroup legend="Notify me about" hint="Pick as many as you like.">
<Checkbox label="Comments" checked />
<Checkbox label="Mentions" />
<Checkbox label="Releases" />
</CheckboxGroup>

For options that need a description, an icon or a price, see Choice card.

Add

npx @ava-ui/apogee add checkbox-group

Depends on utils. Use with checkbox.

Usage

---
import CheckboxGroup from '@/components/apogee/CheckboxGroup/CheckboxGroup.astro'
import Checkbox from '@/components/apogee/Checkbox/Checkbox.astro'
---
<CheckboxGroup legend="Size" direction="row">
  <Checkbox label="S" />
  <Checkbox label="M" />
  <Checkbox label="L" />
</CheckboxGroup>

Anatomy

A <fieldset> with a <legend>, the controls in the default slot, and an optional hint or error paragraph the fieldset is described by.

API

@composable. Any other native <fieldset> attribute (disabled, form) passes through.

Prop Type Default Description
legend string — Group label (required).
hint string — Helper text under the controls.
error string — Error text; replaces the hint, sets aria-invalid.
direction 'row' | 'column' 'column' Lay the controls out in a row (wraps) or a column.
id string auto Fieldset id; hint/error ids derive from it.
class string — Extra classes on the fieldset, merged last.

Variants

Column
Row
Show code
<CheckboxGroup legend="Column">…</CheckboxGroup>
<CheckboxGroup legend="Row" direction="row">…</CheckboxGroup>

States

With hint

Helper text.

With error
Disabled
Show code
<CheckboxGroup legend="With hint" hint="Helper text.">…</CheckboxGroup>
<CheckboxGroup legend="With error" error="Pick at least one.">…</CheckboxGroup>
<CheckboxGroup legend="Disabled" disabled>…</CheckboxGroup>

Error tint

The group’s error tints every control inside it; the children need no hasError of their own.

Channels
Channels
Show code
<CheckboxGroup legend="Channels" error="Pick at least one">
<Checkbox label="Email" />
<Checkbox label="SMS" />
</CheckboxGroup>

Examples

A parent checkbox in the mixed state over its children. Wire the parent to the children yourself; indeterminate only sets the first paint:

Notifications
Show code
<CheckboxGroup legend="Notifications">
<Checkbox indeterminate label="All channels" />
<div class="ms-6 flex flex-col gap-2">
  <Checkbox label="Email" checked />
  <Checkbox label="Push" />
  <Checkbox label="SMS" />
</div>
</CheckboxGroup>

Accessibility

  • Native <fieldset>/<legend>: screen readers announce the legend with each control.
  • Hint and error are linked through aria-describedby; the error has role="alert".
  • Pass hasError to the controls that are wrong so they draw the critical border too.

Tokens

Token Used for
--foreground-neutral Legend
--foreground-neutral-faded Hint
--foreground-critical Error

Do / Don’t

  • Do write the legend as the question or category (“Plan”, “Notify me about”).
  • Do use direction="row" for two or three short options only.
  • Don’t nest one group inside another.

Content

  • Legend in sentence case, no trailing colon.
  • Error text says what to do (“Pick at least one”), not what went wrong.

Related

CheckboxA native checkbox with a custom look. Toggle a single option, or one item in a multi-select list.
RadioGroupA fieldset of Radio controls with one legend, hint and error.
FieldThe labeled-field scaffold — label, control, and hint/error — wired for accessibility.