ki-checkbox-group
@kimen/elements/ki-checkbox-group- Source
- Agent reference
Use ki-checkbox-group when people can choose several answers to one question.
Give the group a visible label and place each option directly in its default
slot as a ki-checkbox with its own label and value.
<ki-checkbox-group label="Regions" name="regions" min="1"help-text="Choose the regions you serve." error-text="Choose at least one region."><ki-checkbox value="eu" checked>Europe</ki-checkbox><ki-checkbox value="am">Americas</ki-checkbox><ki-checkbox value="apac">Asia-Pacific</ki-checkbox></ki-checkbox-group>Each checked option adds a form entry with the group’s name. Set min and
max for selection limits. The group shows its error after a blocked
submission or after focus leaves the group. Tab moves through the enabled
options and Space toggles the focused option.
Set a fresh JavaScript value array to update the selection. Listen for
ki-change to receive the selection after a user toggle.
API reference
When to use: people may select several visible options that share a question, form field, and optional selection limits.
When not to use: mutually exclusive choices (use ki-radio-group) or an immediate on/off setting (use ki-switch). Provide a group label.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Makes the group unavailable and excludes it from form submission. |
error-text | errorText | string | undefined | – | Localized message displayed for a failing selection limit. |
help-text | helpText | string | undefined | – | One line of guidance displayed under the choices. |
label | label | string | – | Visible legend and accessible name for these choices. |
max | max | number | undefined | – | Maximum number of checked options, as a nonnegative integer. |
min | min | number | undefined | – | Minimum number of checked options, as a nonnegative integer. |
name | name | string | undefined | – | Form-data key repeated for each selected option. |
orientation | orientation | "horizontal" | "vertical" | 'vertical' | Lays choices out vertically or in a wrapping horizontal row. |
Events
| Event | Detail type | Description |
|---|---|---|
ki-change | CustomEvent<KiCheckboxGroupChangeDetail> | Fires once for a committed user toggle with a copy of the current selection. |
Slots
| Slot | Description |
|---|---|
| (default) | Direct ki-checkbox options, each with its own visible label and value. Put form naming and constraints on the group. |
CSS parts
| Part | Description |
|---|---|
error | Polite error message shown in place of the help. |
help | Guidance below the options and the group's accessible description. |
label | Legend that names the group. |
CSS custom properties
The public styling contract of ki-checkbox-group: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-checkbox-group-gap | Space between checkbox options and the group label and messages. |
--ki-radio-group-label-font-size | dimension used by the radio group component for label font size. |
--ki-radio-group-label-font-weight | font weight used by the radio group component for label font weight. |
--ki-radio-group-label-line-height | dimension used by the radio group component for label line height (closest measured analogue: Radio_label sm 13/20; no group-title master exists — low-confidence refinement). |
--ki-text-danger-high-em | semantic color for text danger high em. |
--ki-text-high-em | semantic color for text high em. |
--ki-text-med-em | semantic color for text med em. |
--ki-text-supporting | Supporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted). |
--ki-typography-family-body | semantic font family for typography family body. |
--ki-typography-line-height-caption-2 | semantic dimension for typography line height caption 2. |
--ki-typography-size-caption-2 | semantic dimension for typography size caption 2. |
--ki-typography-weight-body-normal | semantic font weight for typography weight body normal. |