Skip to content
Kimenpre-v1documentation home
Color scheme

ki-checkbox-group

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.

Theme for this example
Color scheme for this example
Europe Americas Asia-Pacific
<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

AttributePropertyTypeDefaultDescription
disableddisabledbooleanfalseMakes the group unavailable and excludes it from form submission.
error-texterrorTextstring | undefined–Localized message displayed for a failing selection limit.
help-texthelpTextstring | undefined–One line of guidance displayed under the choices.
labellabelstring–Visible legend and accessible name for these choices.
maxmaxnumber | undefined–Maximum number of checked options, as a nonnegative integer.
minminnumber | undefined–Minimum number of checked options, as a nonnegative integer.
namenamestring | undefined–Form-data key repeated for each selected option.
orientationorientation"horizontal" | "vertical"'vertical'Lays choices out vertically or in a wrapping horizontal row.

Events

EventDetail typeDescription
ki-changeCustomEvent<KiCheckboxGroupChangeDetail>Fires once for a committed user toggle with a copy of the current selection.

Slots

SlotDescription
(default)Direct ki-checkbox options, each with its own visible label and value. Put form naming and constraints on the group.

CSS parts

PartDescription
errorPolite error message shown in place of the help.
helpGuidance below the options and the group's accessible description.
labelLegend 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.

TokenDescription
--ki-checkbox-group-gapSpace between checkbox options and the group label and messages.
--ki-radio-group-label-font-sizedimension used by the radio group component for label font size.
--ki-radio-group-label-font-weightfont weight used by the radio group component for label font weight.
--ki-radio-group-label-line-heightdimension 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-emsemantic color for text danger high em.
--ki-text-high-emsemantic color for text high em.
--ki-text-med-emsemantic color for text med em.
--ki-text-supportingSupporting 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-bodysemantic font family for typography family body.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-weight-body-normalsemantic font weight for typography weight body normal.

Workshop

Open ki-checkbox-group in Storybook