# dds-checkbox-group ## Overview Groups related `dds-checkbox` members under a shared label, hint and error. Each checkbox stays its own form control and tab stop; the group names them as a set, can disable or lock them together, and owns an explicit error. Selection is read from the members, and the group reports the whole selection through `ddsChange`. ## Usage ### Checkbox-group Names a set of related `dds-checkbox` members and gives them a shared label, hint and error. Put the checkboxes in the default slot and the label in the `label` slot. ```html Notifications Email SMS Push ``` #### Form behaviour The group is not the form control. Each `dds-checkbox` is its own control, so put `name` and `value` on the members. They submit, reset with `form.reset()` and take part in validation as they would outside a group. The group has no `value` of its own: read the selection from the members' `checked`. #### Label, hint and error The `label` slot names the group, and it takes rich content. It is hidden while empty. With no visible label, name the group with `aria-label` on the host. Do not use `aria-labelledby` or `aria-describedby` on the host: an id reference cannot cross the shadow boundary, so they are not forwarded. ```html Email SMS ``` Set `hint` for supporting text. It is shown below the label and announced as the group's description. Set `error` to a message to mark the group invalid: the message is shown below the label, announced with `aria-invalid`, and becomes the group's custom validity message, so the form cannot submit while it is set. Clear it to make the group valid again. The group has no `required`, because it cannot supply a validation message for "choose at least one". Set `error` yourself when your own check fails. ```html Notifications Email SMS ``` #### Layout, size and shape `orientation` is `vertical`, the default, or `horizontal`, which flows the members in a wrapping row. `size` is `s` or `m` and `shape` is `square` or `circle`. Setting either applies it to every member, so a group cannot mix sizes or shapes. Leave them off and each member keeps its own `size` and `shape`. ```html Notifications Email SMS ``` #### Disabled and read-only `disabled` disables every member and removes them from the tab order. `readonly` keeps them focusable but stops the user changing them. Clearing either only undoes what the group set: a member you disabled yourself stays disabled. An ancestor `
` disables the group as well. ```html Notifications Email SMS ``` To lock a single option, set `disabled` or `readonly` on that `dds-checkbox`. #### Events The group emits `ddsChange` when the user changes a member. `event.detail.value` lists the `value` of every member that is checked and not disabled, in DOM order, which is what the form would submit. `event.detail.changed` names the member that just flipped. Setting a member's `checked` in code does not emit. ```js const group = document.querySelector("dds-checkbox-group"); group.addEventListener("ddsChange", (event) => { const { value, changed } = event.detail; console.log(value, changed); }); ``` The member's own `ddsChange` stops at the group, so a listener on the group or above hears one event per change. A listener on `document` or a `
` therefore does not receive member `ddsChange` events from inside a group; listen on the group instead. A listener on a `dds-checkbox` itself still fires. #### Keyboard The group follows the [WAI-ARIA Authoring Practices checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/), applied to each member: Tab moves between checkboxes and Space toggles the focused one. This deviates from a radio-style group: every checkbox is its own tab stop and arrow keys do nothing, because each checkbox can be chosen independently. A disabled member leaves the tab order. ## Properties | Property | Attribute | Description | Type | Default | | ------------- | ------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------ | | `disabled` | `disabled` | Disables every member and removes them from the tab order. | `boolean` | `false` | | `error` | `error` | An error message shown below the label. While set, the group is invalid and announced as invalid. | `string \| undefined` | `undefined` | | `hint` | `hint` | Supporting text shown below the label and announced as the group's description. | `string \| undefined` | `undefined` | | `orientation` | `orientation` | Whether the members stack vertically or flow in a wrapping row. | `"horizontal" \| "vertical"` | `"vertical"` | | `readonly` | `readonly` | Prevents the user from changing any member while keeping them focusable. | `boolean` | `false` | | `shape` | `shape` | Sets the shape of every member. Members keep their own shape when omitted. | `"circle" \| "square" \| undefined` | `undefined` | | `size` | `size` | Sets the size of every member. Members keep their own size when omitted. | `"m" \| "s" \| undefined` | `undefined` | ## Events | Event | Description | Type | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | | `ddsChange` | Emitted when the user changes any member, with the group's whole selection. The member's own `ddsChange` stops at the group. This event will not emit when programmatically setting a member's `checked` property. | `CustomEvent` | ## Slots | Slot | Description | | --------- | --------------------------------------------------- | | | The `dds-checkbox` members of the group. | | `"label"` | The label that names the group. Hidden while empty. | ## Shadow Parts | Part | Description | | -------- | --------------------------------------------- | | `"root"` | The outermost element inside the shadow root. | ---------------------------------------------- *Built with [StencilJS](https://stenciljs.com/)*