CheckboxGroup

CheckboxGroup renders a complete, labelled set of Checkbox controls from options. Choose it when people can select any combination from one decision; use RadioGroup when exactly one answer is allowed.

Examples

Several independent choices

defaultValue starts an uncontrolled group with selected values. Option-level hint gives context to an individual choice without separating it from its label.

Notification channels

EmailRelease notes and account updatesPush notificationsText messages

Choose every channel you want to use.

A compact group with validation

A row works for short labels. error replaces hint, and a disabled option remains visible when its absence would make the available formats confusing.

Data exports

CSVJSONXLSX

Choose at least one export format.

When to use

Use CheckboxGroup for a related set of options where zero, one or many values can be selected and the whole set needs one label or validation message.

Reach for something else when:

Exactly one option must be selected — use RadioGroup so the selection model is explicit.
Each choice needs its own position or surrounding content — compose standalone Checkbox items.
The change takes effect immediately — use Switch for a single setting that is applied as it is toggled.

Accessibility

Renders a div with role="group"; a supplied label is connected through generated aria-labelledby, combined with any id you provide.
Its composed controls are native checkbox inputs. Space toggles the focused checkbox and every option remains independently checked.
hint and error render visibly below the choices, with error taking precedence. The component does not attach either message with aria-describedby.
In controlled mode, onChange reports the full next string[]; the caller must update value to reflect the change.

API and code

Name	Type	Required	Description
`label`	`ReactNode`	—	Label rendered above the group.
`hint`	`ReactNode`	—	Helper text rendered below the group when no error is present.
`error`	`ReactNode`	—	Error message rendered below the group in place of `hint`.
`options`	`CheckboxGroupOption[]`	—	Checkbox options rendered by the group. Default: `[]`.
`value`	`string[]`	—	Selected values in controlled mode.
`defaultValue`	`string[]`	—	Initially selected values in uncontrolled mode. Default: `[]`.
`onChange`	`(value: string[]) => void`	—	Called with the next selected values.
`direction`	`'column' \| 'row'`	—	Layout direction for the options. Default: `"column"`.

Without React, compose native checkboxes in the shared field and choice-group classes:

html

<div class="lyra-field" role="group" aria-labelledby="notification-channels">
  <span class="lyra-label" id="notification-channels">Notification channels</span>
  <div class="lyra-choicegroup">
    <label class="lyra-check-row">
      <input class="lyra-checkbox" type="checkbox" name="channels" value="email" checked />
      <span>Email</span>
    </label>
    <label class="lyra-check-row">
      <input class="lyra-checkbox" type="checkbox" name="channels" value="push" />
      <span>Push notifications</span>
    </label>
  </div>
  <span class="lyra-hint">Choose every channel you want to use.</span>
</div>

<lyra:checkbox-group> Generated from lyra-ds/blade v0.10.0.

Prop	Default	Required	Example values
`label`	`null`	—	—
`hint`	`null`	—	`Choose one`
`error`	`null`	—	`Required`
`options`	`[]`	—	—
`value`	`null`	—	—
`defaultValue`	`[]`	—	—
`direction`	`'column'`	—	`row`
`name`	`null`	—	—

blade

<lyra:checkbox-group
    name="notifications"
    label="Email notifications"
    hint="You can change this at any time."
    :options="[
        ['value' => 'mentions', 'label' => 'Mentions', 'hint' => 'When someone mentions you in a comment'],
        ['value' => 'deploys', 'label' => 'Deploys'],
        ['value' => 'billing', 'label' => 'Billing', 'disabled' => true],
    ]"
    :default-value="['mentions']"
/>