Skip to content
Kimenpre-v1documentation home
Color scheme

ki-radio-group

A token-styled radio group that owns selection, keyboard coordination and form participation for slotted ki-radio options — for choosing exactly one of a small set that should all be visible at once.

Theme for this example
Color scheme for this example
Monthly Yearly Lifetime
<ki-radio-group label="Billing period" name="billing" value="monthly">
<ki-radio value="monthly">Monthly</ki-radio>
<ki-radio value="yearly">Yearly</ki-radio>
<ki-radio value="lifetime" disabled>Lifetime</ki-radio>
</ki-radio-group>

The group contributes name/value to FormData, honors required, and re-dispatches the composed change event at the host:

Theme for this example
Color scheme for this example
1-10 11-50 51+ Continue
<form onsubmit="event.preventDefault()">
<ki-radio-group label="Team size" name="size" required>
<ki-radio value="s">1-10</ki-radio>
<ki-radio value="m">11-50</ki-radio>
<ki-radio value="l">51+</ki-radio>
</ki-radio-group>
<ki-button variant="primary">Continue</ki-button>
</form>

When to use: a person must choose exactly one of a small set of mutually exclusive options that should all be visible at once.

When not to use: many options or tight space (use ki-select), independent on/off settings (use ki-checkbox or ki-switch), multiple selection, or authored selection on options; set this group's value instead.

Properties & attributes

AttributePropertyTypeDefaultDescription
disableddisabledbooleanfalseMakes the whole group unavailable, skips it in Tab order and removes its form entry. When NOT to use: do not use disabled for pending/loading semantics.
error-texterrorTextstring | undefined–Message shown in place of the help text once a required group is left without a choice, and its validationMessage ("Choose a plan"). Without it the browser's own message shows, in the browser's language. An error set with setCustomValidity outranks it. When NOT to use: do not use it for server-side or cross-field errors; call setCustomValidity for those.
help-texthelpTextstring | undefined–One line of help under the options, read with the group as its description: what the choice decides. While an error shows, the error takes its place. When NOT to use: do not repeat the label, and do not use it for error messages; use error-text.
labellabelstring–Visible label and accessible-name source for the radiogroup. When NOT to use: do not omit it; unlabeled groups fail accessibility gates.
label-hintlabelHintstring | undefined–Short text shown after the group label and read with it as part of the radiogroup name, so people know before submitting whether to choose: "(optional)" on the few optional questions of a mostly required form, or "(required)" the other way round, in the page's own language. It changes no validation; set required for that, and keep the two consistent. When NOT to use: do not put what the choice decides in it (use help-text), errors (use error-text), or a repeat of the label.
namenamestring | undefined–Form-data key for the selected option's value. Omit when the group should not contribute a form entry. When NOT to use: do not put name on ki-radio options; their internal native inputs are intentionally unnamed.
requiredrequiredbooleanfalseRequires one selected option for form submission. The group uses platform valueMissing from its internal native radio inputs. When NOT to use: do not use required when no answer is acceptable.
sizesize"md" | "sm"'md'Token-backed size of every ki-radio the group holds: the circle is 18 or 20px in onmars, and sm takes the smaller option label (13/20, 8px away). The group decides for all its options; the group's own label, help and error keep their size. An unrecognized value matches no style rule and keeps the medium metrics. When to use: match the size of the text and controls around the group. When NOT to use: do not pick a smaller size to fit a dense region or a larger one for touch; declare data-ki-density on the region instead, which composes with every size.
valuevaluestring''Projection of the current selection. The initial attribute selects the first matching option; unmatched values leave the group unselected and operable. Assigning the property updates selection silently. When NOT to use: never author selection on ki-radio; set this value.

Events

EventDetail typeDescription
changeEventFired once after the user selects a different radio, composed across the shadow boundary; value is already current when listeners run. When to use: react to the committed choice. When NOT to use: do not expect it for programmatic value writes, which are silent.

Slots

SlotDescription
(default)ki-radio options. Document order is navigation order.

CSS parts

PartDescription
errorError line shown in place of the help text while the group is invalid after the person submitted; a polite live region, starting with a decorative error symbol.
helpHelp line under the options, read as the radiogroup description.
labelVisible group label and accessible-name source.
label-hintThe label-hint text after the group label text, inside the label and part of the radiogroup's accessible name; rendered only while a hint is set.

CSS custom properties

The public styling contract of ki-radio-group: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-radio-group-gapdimension used by the radio group component for gap.
--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-hint-fgcolor used by the radio group component for the label hint after the label text (spec 047: the supporting-text role, a declared a11y deviation from the MarsUI Input_label support text Text/low_em, which reads 2.8-3.13:1 on the onmars light surfaces; under more contrast it strengthens with every other supporting text).
--ki-radio-group-label-hint-gapdimension used by the radio group component for the gap between the label text and the label hint (MarsUI Input_label: Space/xs 4px).
--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-radio-sm-control-sizedimension used by the radio component for the sm circle (Radio 10053:1943 sm: 18px in a 20px cell).
--ki-radio-sm-dot-sizedimension used by the radio component for the sm dot (Radio 10053:1943 sm: 8px, as at md).
--ki-radio-sm-gapdimension used by the radio component for the sm gap between control and label (Radio-label 10100:3931 sm binds Space/md, 8px; spec 050 D4).
--ki-radio-sm-label-font-sizedimension used by the radio component for the sm label font size (Radio-label 10100:3931 sm: UI/para 13/20; spec 050 D4).
--ki-radio-sm-label-line-heightdimension used by the radio component for the sm label line height (Radio-label 10100:3931 sm: UI/para 13/20).
--ki-radio-sm-min-targetdimension used by the radio component for the sm min target: 24px, the WCAG 2.5.8 minimum, above the master's 20px cell.
--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.

The label prop is mandatory — unlabeled groups fail accessibility gates. Selection follows the APG radio-group pattern: arrow keys move it, the group is one tab stop. For many options or tight space use ki-select; for independent on/off settings use ki-checkbox or ki-switch.

Open ki-radio-group in Storybook