ki-radio-group
@kimen/elements/ki-radio-group- Source
- Agent reference
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.
<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>Examples
Section titled “Examples”In a form
Section titled “In a form”The group contributes name/value to FormData, honors required, and
re-dispatches the composed change event at the host:
<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>API reference
Section titled “API reference”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
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
disabled | disabled | boolean | false | Makes 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-text | errorText | string | 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-text | helpText | string | 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. |
label | label | string | – | Visible label and accessible-name source for the radiogroup. When NOT to use: do not omit it; unlabeled groups fail accessibility gates. |
label-hint | labelHint | string | 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. |
name | name | string | 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. |
required | required | boolean | false | Requires 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. |
size | size | "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. |
value | value | string | '' | 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
| Event | Detail type | Description |
|---|---|---|
change | Event | Fired 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
| Slot | Description |
|---|---|
| (default) | ki-radio options. Document order is navigation order. |
CSS parts
| Part | Description |
|---|---|
error | Error 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. |
help | Help line under the options, read as the radiogroup description. |
label | Visible group label and accessible-name source. |
label-hint | The 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.
| Token | Description |
|---|---|
--ki-radio-group-gap | dimension used by the radio group component for gap. |
--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-hint-fg | color 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-gap | dimension 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-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-radio-sm-control-size | dimension used by the radio component for the sm circle (Radio 10053:1943 sm: 18px in a 20px cell). |
--ki-radio-sm-dot-size | dimension used by the radio component for the sm dot (Radio 10053:1943 sm: 8px, as at md). |
--ki-radio-sm-gap | dimension 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-size | dimension 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-height | dimension used by the radio component for the sm label line height (Radio-label 10100:3931 sm: UI/para 13/20). |
--ki-radio-sm-min-target | dimension 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-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. |
Accessibility
Section titled “Accessibility”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.