Checkbox Group
Checkbox groups collect related options under one prompt. Use them when several checkboxes answer the same question and need shared context, description, or validation.
Component
Use fd-checkbox-group to wrap related fd-checkbox options in a native <fieldset> with a shared <legend>. The group handles vertical or horizontal layout, optional description and error text, and the “select at least one” validation pattern.
When to use
- Several checkboxes answer one prompt — Communication preferences, account access scopes, notification channels, and similar grouped decisions.
- The options need shared help text — Group-level description reduces repetition when the same clarification applies to every option.
- At least one option is required — Use group-level validation when the rule is “select one or more.”
When not to use
- Don’t use a group for a single checkbox — A standalone checkbox is simpler and clearer.
- Don’t use a group when only one option may be selected — That is a radio-group pattern.
- Don’t rely on horizontal layout for dense lists — Horizontal groups are only appropriate for short, low-count option sets.
Examples
Properties
| Name | Type | Default | Description |
|---|---|---|---|
orientation | "vertical" | "horizontal" | vertical | Layout direction for the checkbox set |
required | boolean | false | Requires at least one enabled checkbox to be selected |
disabled | boolean | false | Disables the group and temporarily disables enabled child checkboxes |
label | string | `` | Fallback legend text when no legend slot content is provided |
Slots
| Name | Description |
|---|---|
legend | Optional replacement for the authored legend text |
description | Group-level help text announced from the fieldset |
| (default) | One or more fd-checkbox children |
error | Group-level validation message shown and announced while invalid |
Events
| Name | Detail | Description |
|---|---|---|
fd-checkbox-group-change | { value: string, values: string[] } | Fired when the checked set changes. value mirrors the first selected value in DOM order. |
Compatibility note:
fd-checkbox-groupstill fires deprecatedfd-group-changewith{ checkedValues: string[] }during the compatibility window.- New consumer code should listen to
fd-checkbox-group-change.
CSS custom properties
| Name | Default | Description |
|---|---|---|
--fd-checkbox-group-max-width | 32rem | Maximum inline size of the group |
--fd-checkbox-group-legend-gap | var(--fdic-spacing-xs, 8px) | Space between the legend and the description or items |
--fd-checkbox-group-description-gap | var(--fdic-spacing-sm, 12px) | Space below the description before the checkbox items |
--fd-checkbox-group-gap | var(--fdic-spacing-sm, 12px) | Gap between checkbox items |
Shadow parts
| Name | Description |
|---|---|
fieldset | Native fieldset wrapper |
legend | Native legend element |
description | Group-level description wrapper |
items | Container for slotted fd-checkbox children |
error | Group-level error message wrapper |
Best practices
Do
Write the legend as a full prompt
The legend should make sense before the user reads any individual option labels.
Don't
Use the legend as a vague heading
Generic headings make the user scan every option just to understand the question.
Do
Keep the group vertical by default
Vertical stacking is easier to scan, especially when labels wrap across multiple lines.
Don't
Force wide horizontal layouts for long labels
That increases reading effort and can make the question harder to parse.
Content guidelines
- Use plain-language legends.
- Place required text in the legend. Example: “Communication preferences (required)”.
- Use one group-level error message. For “select at least one” rules, the error belongs to the group, not to every checkbox.
Accessibility
fd-checkbox-grouprenders a real native<fieldset>and<legend>in Shadow DOM.- Group-level
aria-describedbyis computed. Description text is referenced only when present, and error text is referenced only when present and the group is invalid. - The group participates in validation through
ElementInternals, but submits no form value of its own. Individualfd-checkboxchildren submit their ownname/valuepairs. checkValidity()updates and returns validity without revealing invalid state.reportValidity(), form submit attempts, and focus leaving the logical group after user interaction are visibility boundaries. When the group is invalid at that point, the host getsdata-user-invalidand the internal<fieldset>getsaria-invalid="true".aria-invalidis present iffdata-user-invalidis present, and it clears in the same update cycle when the group becomes valid or when the form reset path runs.- Provide one authored group-level error message in the
errorslot whenever the group can block submission. Missing error copy is incomplete usage even though invalid styling still appears.
Known limitations
- Dynamic child disabled toggles while the group is disabled are out of scope in v1 — Set child-specific disabled states before disabling the group or after re-enabling it.
- Legend, description, and error treatment are still awaiting full Figma comps for all orientations — The shipped implementation follows the approved proposal and current issue guidance.
- Manual AT validation remains a release gate — VoiceOver and NVDA checks are still required for description and error announcement behavior.