Checkbox group
Checkboxes grouped into one form control with a value array, a group label and an at-least-one rule.
c2-checkbox-group
Groups c2-checkbox options into one form control with one value array — the multi-select counterpart of
c2-radio-group. The group owns the name (every checked option is submitted under it), group-level disabled
and a required rule meaning "at least one". Options may sit anywhere inside the group, wrapped in other elements,
and each stays its own tab stop, as native checkboxes are. The label and description slots name the group for
assistive technology (role="group").
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
value | string[] | [] | value of every checked option, in document order. Setting it checks exactly the matching options. As an
attribute, the values are separated by ; (value="email;sms"). |
name | string | — | Form field name. Every checked option is submitted under it; leave the options themselves unnamed. |
disabled | boolean | false | Disables every option. |
required | boolean | false | Requires at least one option to be checked for the form to be valid. |
orientation | CheckboxGroupOrientation | vertical | Lays the options out in a row instead of a column. |
aria-label | string | — | Accessible name of the group when its heading does not label it. |
Slots
| Name | Description |
|---|---|
(default) | The c2-checkbox options, optionally inside wrapper elements. Give each a value and label text. |
label | Group heading, announced as the group's name. |
description | Supporting text under the heading. |
Events
| Name | Type | Description |
|---|---|---|
input | Event | Fired when the user toggles an option, before change. Read the group's value. |
change | CustomEvent<{ value: string[] }> | Fired after the user toggles an option. detail.value is the new value. Not fired for programmatic changes. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-checkbox-group--gap | pixel | 8px | Space between options. |
--c2-checkbox-group--align-items | align-items | flex-start | stretch makes card-style options fill the width. |
--c2-checkbox-group__header--gap | pixel | 2px | Space between the label and the description. |
--c2-checkbox-group__header--margin-bottom | pixel | 8px | Space between the header and the options. |
--c2-checkbox-group__header__disabled--opacity | opacity | 0.38 | |
--c2-checkbox-group__label--color | color | #18181b | |
--c2-checkbox-group__label--font-size | font-size | 14px | |
--c2-checkbox-group__label--font-weight | font-weight | 500 | |
--c2-checkbox-group__description--color | color | #71717a | |
--c2-checkbox-group__description--font-size | font-size | 12px | |
Text and languages
The text the component shows, in English. It shows another language when the app adds one with addTranslations, under checkbox, and the nearest lang asks for it; any message not translated stays in English. {0}, {1}… stand for the values a message carries. Languages guide.
| Key | English | Values |
|---|---|---|
valueMissing | Please check this box. | — |
groupValueMissing | Please select at least one option. | — |
c2-checkbox
A checkbox with native <input type="checkbox"> behaviour. The visible box sits centred in a square touch target
(state-layer--size) that doubles as the hover layer; that layer is transparent unless a
state-layer__hover__*--color is set, so the default look is quiet. Text in the default slot becomes the
checkbox's label (clicking it toggles the box), with an optional description underneath; without either the
element is the bare box. Put several in a c2-checkbox-group for one value array.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
checked | boolean | false | Whether the checkbox is checked. |
indeterminate | boolean | false | Shows the mixed state (neither checked nor unchecked), e.g. for a parent of a partially selected group. |
disabled | boolean | false | Disables the control: it no longer toggles and is rendered dimmed. |
name | string | — | Form field name forwarded to the inner input. |
value | string | on | Value submitted while checked. |
required | boolean | false | Requires the checkbox to be checked for the form to be valid. |
aria-label | string | — | Accessible name used when no visible label names the checkbox. |
aria-labelledby | undefined | string | — | Id of the element that labels the checkbox. |
aria-describedby | undefined | string | — | Id of the element that describes the checkbox. |
Slots
| Name | Description |
|---|---|
(default) | Label text beside the box. Clicking it toggles the checkbox, and it names the checkbox for assistive technology. |
description | Supporting text shown under the label. |
checkmark | Icon shown when checked: an inline SVG, a c2-feather-* icon or a c2-mat-icon. Defaults to a check. |
mixedmark | Icon shown when indeterminate. Defaults to a dash. |
uncheckmark | Icon shown when unchecked. Empty by default. |
Events
| Name | Type | Description |
|---|---|---|
change | Event | Re-dispatched from the inner input when the checked state changes. |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
checkmark | Wrapper containing the checkmark slot or fallback mark while checked. |
mixedmark | Wrapper containing the mixedmark slot or fallback mark while indeterminate. |
uncheckmark | Wrapper containing the optional uncheckmark slot while unchecked. |
label | Region containing the default slot (the label text). |
description | Region containing the description slot below the label. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-checkbox__container--height | pixel | 18px | |
--c2-checkbox__container--width | pixel | 18px | |
--c2-checkbox__container--border-top-left-radius | border-radius | 4px | |
--c2-checkbox__container--border-top-right-radius | border-radius | 4px | |
--c2-checkbox__container--border-bottom-left-radius | border-radius | 4px | |
--c2-checkbox__container--border-bottom-right-radius | border-radius | 4px | |
--c2-checkbox__container--border-top | border | 1px solid #bcbcc6 | |
--c2-checkbox__container--border-right | border | 1px solid #bcbcc6 | |
--c2-checkbox__container--border-bottom | border | 1px solid #bcbcc6 | |
--c2-checkbox__container--border-left | border | 1px solid #bcbcc6 | |
--c2-checkbox__container--background-color | color | transparent | |
--c2-checkbox__container__selected--background-color | color | #476ef9 | |
--c2-checkbox__container__selected--border-top | border | 0px solid transparent | |
--c2-checkbox__container__selected--border-right | border | 0px solid transparent | |
--c2-checkbox__container__selected--border-bottom | border | 0px solid transparent | |
--c2-checkbox__container__selected--border-left | border | 0px solid transparent | |
--c2-checkbox__container__selected__hover--background-color | color | — | |
--c2-checkbox__container__focus--outline | outline | 2px solid rgba(71, 110, 249, 0.4) | |
--c2-checkbox__container__focus--outline-offset | pixel | 2px | |
--c2-checkbox__container__disabled--opacity | opacity | 0.38 | |
--c2-checkbox__container__error--border-color | color | #dc2626 | Border of an unchecked box while an enclosing c2-form-field shows an error. |
--c2-checkbox__checkmark--size | pixel | 12px | |
--c2-checkbox__checkmark--color | color | #ffffff | |
--c2-checkbox__mixedmark--size | pixel | 12px | |
--c2-checkbox__mixedmark--color | color | #ffffff | |
--c2-checkbox__uncheckmark--size | pixel | 12px | |
--c2-checkbox__uncheckmark--color | color | #ffffff | |
--c2-checkbox__state-layer--size | pixel | 32px | |
--c2-checkbox__state-layer--border-top-left-radius | border-radius | 6px | |
--c2-checkbox__state-layer--border-top-right-radius | border-radius | 6px | |
--c2-checkbox__state-layer--border-bottom-left-radius | border-radius | 6px | |
--c2-checkbox__state-layer--border-bottom-right-radius | border-radius | 6px | |
--c2-checkbox__state-layer__hover__unselected--color | color | — | |
--c2-checkbox__state-layer__hover__selected--color | color | — | |
--c2-checkbox__field--gap | pixel | 4px | Space between the box's touch target and the label. |
--c2-checkbox__label--color | color | inherit | |
--c2-checkbox__label--font-size | font-size | inherit | |
--c2-checkbox__label--font-weight | font-weight | inherit | |
--c2-checkbox__label--line-height | line-height | inherit | |
--c2-checkbox__label__disabled--opacity | opacity | 0.38 | |
--c2-checkbox__description--color | color | #71717a | |
--c2-checkbox__description--font-size | font-size | 12px | |
--c2-checkbox__description--line-height | line-height | 1.4 | |
Text and languages
The text the component shows, in English. It shows another language when the app adds one with addTranslations, under checkbox, and the nearest lang asks for it; any message not translated stays in English. {0}, {1}… stand for the values a message carries. Languages guide.
| Key | English | Values |
|---|---|---|
valueMissing | Please check this box. | — |
groupValueMissing | Please select at least one option. | — |