# CheckboxGroup

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

URL: https://apogee.avaui.dev/docs/checkbox-group
Last updated: 2026-10-15

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

Last updated October 15, 2026

```astro
<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](https://apogee.avaui.dev/docs/choice-card).

## Add

```sh
npx @ava-ui/apogee add checkbox-group
```

Depends on `utils`. Use with `checkbox`.

## Usage

```astro
---
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

```astro
<CheckboxGroup legend="Column">…</CheckboxGroup>
<CheckboxGroup legend="Row" direction="row">…</CheckboxGroup>
```

## States

```astro
<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.

```astro
<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:

```astro
<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.

](https://apogee.avaui.dev/docs/checkbox)[

RadioGroupA fieldset of Radio controls with one legend, hint and error.

](https://apogee.avaui.dev/docs/radio-group)[

FieldThe labeled-field scaffold — label, control, and hint/error — wired for accessibility.

](https://apogee.avaui.dev/docs/field)