Checkbox Group
<cs-checkbox-group>
Checkbox groups wrap a set of related checkboxes or switches so they share a label, hint, and grouping semantics.
Checkboxes in a group remain independent form controls with their own name, value, and validation. The group exists to provide a shared label, hint, and accessible grouping.
Examples
Label
Use the label attribute to give the group an accessible label. For labels that contain HTML, use the label slot instead.
Hint
Add a descriptive hint to a checkbox group with the hint attribute. For hints that contain HTML, use the hint slot instead.
Orientation
Checkbox groups stack vertically by default. Set the orientation attribute to horizontal to lay them out in a row.
Size
The size of grouped checkboxes and switches is determined by the checkbox group’s size attribute. Any size set on individual items will be overridden.
Disabled
A checkbox group itself can’t be disabled. Add the disabled attribute to individual checkboxes to disable them.
Switches
A checkbox group also works with switches.
Required
The required attribute adds a visual indicator to the group’s label. Because each checkbox is an independent control, the checkbox group doesn’t enforce the requirement. Set the required property on the checkbox or call its setCustomValidity() method to control validation.
API
Importing
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick this component, use one of the following snippets.
import '@cruglobal/cornerstone-components/components/checkbox-group/checkbox-group.js';
import './cornerstone/components/checkbox-group/checkbox-group.js';
import CsCheckboxGroup from '@cruglobal/cornerstone-components/react/checkbox-group/index.js';
Slots
Learn more about using slots.
| Name | Description |
|---|---|
| (default) | The default slot where <cs-checkbox> or <cs-switch> elements are placed. |
hint | Text that describes how to use the checkbox group. Alternatively, you can use the hint attribute. |
label | The checkbox group's label. Required for proper accessibility. Alternatively, you can use the label attribute. |
Attributes & Properties
Learn more about attributes and properties.
| Property | Attribute | Description | Type | Default | Reflects |
|---|---|---|---|---|---|
hint | hint | The checkbox group's hint. If you need to display HTML, use the hint slot instead. | string | '' | — |
label | label | The checkbox group's label. Required for proper accessibility. If you need to display HTML, use the label slot instead. | string | '' | — |
orientation | orientation | The orientation in which to show grouped checkboxes. | 'horizontal' | 'vertical' | 'vertical' | Yes |
required | required | Indicates that at least one option should be selected. This only adds a visual indicator to the label. To enforce the requirement, use the required attribute on the individual checkboxes and/or their setCustomValidity() method. | boolean | false | Yes |
size | size | The group's size. When present, this size will be applied to all <cs-checkbox> and <cs-switch> items inside. | 'xs' | 's' | 'm' | 'l' | 'xl' | — | Yes |
ssrHint | ssr-hint | Only required for SSR. Set to true if you're slotting in a hint element so the server-rendered markup includes the hint before the component hydrates on the client. | boolean | false | — |
ssrLabel | ssr-label | Only required for SSR. Set to true if you're slotting in a label element so the server-rendered markup includes the label before the component hydrates on the client. | boolean | false | — |
CSS Custom Properties
Learn more about CSS custom properties.
| Name | Description | Default |
|---|---|---|
--gap | The gap between grouped checkboxes. | 0.5em |
CSS Parts
Learn more about CSS parts.
| Name | Description | CSS selector |
|---|---|---|
form-control | The form control that wraps the label, group, and hint. | ::part(form-control) |
form-control-input | The element that wraps the grouped checkboxes, exposed as a role="group". | ::part(form-control-input) |
form-control-label | The label. | ::part(form-control-label) |
hint | The hint's wrapper. | ::part(hint) |
Dependencies
This component automatically imports the following elements. Sub-dependencies, if any exist, are included in this list.