Forms

CheckboxGroup

Fieldset wrapper that groups independent checkboxes under a shared legend, description, and group-level error.

import { CheckboxGroup } from '@lostgradient/cinder/checkbox-group';
formgroup
01

Overview

Wraps multiple checkboxes under a shared label and validation context.

Usage

svelte 
<script lang="ts">
  import CheckboxGroup from '@lostgradient/cinder/checkbox-group';
</script>

<CheckboxGroup />
Live preview
02

When to use

Use when
  • Presenting several unrelated checkboxes that share a common heading or validation message.
  • Cascading a disabled state to every child checkbox via native fieldset propagation.
Avoid when
  • Picking exactly one option from a fixed set — use radio-group instead.
03

Examples

Basic checkbox group

Grouped checkboxes under a shared legend with independent checked states.

04

Props

Props for checkbox-group
Name Type Default Required Bindable Description
label text Visible group caption. Rendered as a <legend> inside the <fieldset>. Named label for consistency with every other form control — the element is a <legend> because the group is a fieldset.
description text Helper text below the group; wired via aria-describedby on the fieldset.
error text Group-level validation message. Rendered as a polite live region and referenced by the fieldset's aria-describedby. Also sets aria-invalid="true" on the fieldset itself as a supplementary signal. Note: fieldset-level aria-describedby is not reliably re-announced as focus moves between descendants. This is best-effort supplemental context — if a specific control must announce as invalid on focus, pass error to that <Checkbox> directly.
disabled boolean false Disables every native form control inside via the fieldset's built-in cascade. Renders as the native disabled attribute on <fieldset>.
required boolean false Marks the group required: sets aria-required="true" and data-cinder-required on the fieldset and renders the required asterisk in the legend. It does NOT set required on any child <input> and does NOT enforce native constraint validation. Per-control required must be set on the individual <Checkbox>.
variant 'default' | 'card' 'default' Layout variant. 'default' is a stacked column. 'card' styles each direct child .cinder-checkbox-field as a bordered card row. Always emitted as data-variant on the fieldset. Card variant assumes each direct child of the items container is a single <Checkbox>.
children snippet req Checkbox children.