Checkbox Group

WHEN TO USE

• Several checkboxes answer the same question and the user may choose any number of them, including none.
• The set needs one shared label, one shared helper note, or one shared error — a legend and a field note per group rather than per box.
• Required or disabled applies to the whole set. Setting it once on the group cascades to the children rather than being repeated on each.

WHEN NOT TO USE

• The choices are mutually exclusive — exactly one must be selected. That is a different control with different keyboard behaviour.USE RADIO-GROUP →
• You only want the boxes arranged with spacing between them and there is no shared question, legend or validation. That is arrangement, and it has its own primitive.USE LAYOUT →
• There is one checkbox. A fieldset around a single control adds a grouping that means nothing.USE CHECKBOX →
• The user is choosing several values from a long list. A field that opens keeps the form scannable where twenty checkboxes would not.USE SELECT →

DO

• Give the group a label. It becomes the <legend>, which is what a screen reader reads before each option so the user knows which question they are answering.
• Set isRequired and isDisabled on the GROUP, not on each checkbox — the group pushes them down to its children on update.
• Listen for onCheckboxGroupChange, whose detail carries checkedValues — every currently-checked value in the group — alongside the box that changed.
• Use hideLegend when the surrounding UI already asks the question, rather than dropping label entirely. The legend stays in the accessibility tree.

DON’T

• Don't add an arrangement prop to this component or wrap it in your own flex container to get a row. Its slot content is already nested in a layout — nest the items in <al-layout direction="row" wrap> instead.
• Don't use a checkbox group where the answer is binary. One question with a yes and a no is a single checkbox, or a toggle if it takes effect immediately.
• Don't set the error note without setting the error state, and don't put per-option errors on a group that renders one shared error region.
• Don't nest a checkbox group inside another. Nested fieldsets are announced as nested groups and quickly become impossible to follow by ear.