Skip to content

role group

Radio group draft v0.1.0

Lets people choose exactly one option from a short, visible set.

A radio group shows every option at once, with a legend naming the choice, and lets people check exactly one of them: checking an option unchecks the previous one. Use it when the options are few and worth reading side by side; a long list of options is a Select, and independent on/off options are Checkboxes. The group is one component: the options are its repeated part, each with its own label, description, value and disabled state.

Decisions

From decisions in packages/components/specs/components/radio-group.spec.json, newest first. Every active decision is implemented by the spec, the tokens, the web implementation and the guidelines.

Anatomy

  • The component is the whole group: a legend, optional help text, the options as a repeated part (label, value, description, checked, disabled) and an error message. On the web it is a fieldset of native radio buttons sharing one name; no single Radio component exists.

    A radio button never stands alone: the choice is the group, and the native group gives the arrow-key behaviour and the one-checked rule for free.

    group-of-native-radios · 2026-10-03 · v0.1.0

    APG: Radio group patternHTML: radio button group (same name, one checked at a time)

Color

  • The radio follows the Checkbox's selection control colors: accent neutral border on the default surface when unchecked; accent brand fill with an on-accent brand dot when checked; hover tints the empty circle with the surface hover color; invalid takes the base error border; disabled the shared disabled colors.

    selection-control-colors · 2026-10-03 · v0.1.0

    radio-group.control.background.*radio-group.control.border-color.*radio-group.control.color.*

    WCAG 1.4.11 Non-text Contrast (AA)

Layout

  • Options stack vertically by default, 8 px apart; the horizontal orientation puts them on one wrapping line, 16 px apart.

    orientations · 2026-10-03 · v0.1.0

    radio-group.container.gap.*

Size

  • Two sizes: small (16 px radio, 14 px label) and medium (20 px radio, 16 px label, the default), as the Checkbox; the radio border is 1.2 px (stroke-width.md) and fully round.

    sizes · 2026-10-03 · v0.1.0

    radio-group.control.size.*radio-group.control.border-widthradio-group.control.border-radiusradio-group.option-label.typography.*radio-group.option-description.typography.*