Radio

OverviewCopy Anchor Link

A radio group forces a single choice among a small, fully-visible set of options. Unlike a checkbox, clicking a radio never toggles it off — it only becomes unselected when a sibling in the same group is selected. There is no mixed state: exactly one radio in a group is checked once a default has been set.

When to useCopy Anchor Link

Single choice, always visible:
Exactly one choice from 2–5 mutually exclusive options (Monthly / Annual, Small / Medium / Large), shown so the user can compare them all at once before choosing.

Not a fit for:

• More than ~5 options — use a select instead, so the list doesn't dominate the page
• Situations where multiple options can be true at once — use checkboxes instead
• A compact, icon-forward mode switch with 2–4 options — a segmented control reads faster

Default selection:
Pre-select a default only when a wrong or unnoticed guess is low-risk and easy to change. Leave the group unselected when the choice is sensitive, consequential, or must be an informed, deliberate decision — don't default someone into consent, data sharing, or anything they should actively opt into.

Required state:

• "Required" applies to the whole group, not to any single radio — you can't mark one option as required, only "at least one of these must be selected." Enforcing it needs a validation message on submit (e.g. "Please select a shipping method").
• Don't rely on that message alone: mark the group as required up front — a required indicator next to the <legend> — so the user knows before they submit, not just after failing to.

AnatomyCopy Anchor Link

A radio is a single <input type="radio"> styled with appearance: none. The selected state is a solid inner circle scaled in from 0 to 1 — there's no icon mask involved, unlike checkbox's checkmark.

Tokens and values that drive each partCopy Anchor Link

SelectionCopy Anchor Link

A radio has only two states — there's no mixed/indeterminate state, since a radio group always resolves to exactly one selection (or none, before a default is chosen).

Radio is fixed at 24×24px — there is no --sm modifier like checkbox has.

Once a user picks an option, the group can't be cleared back to unselected on its own — clicking a radio never unchecks it, and there's no native gesture to undo the pick. If a form genuinely needs a way back to "no selection," add an explicit option for it (None, No preference) rather than expecting users to find a way around a normal radio group.

Interaction statesCopy Anchor Link

All shown checked

No disabled stateCopy Anchor Link

Radios never ship the native "greyed out" disabled look. If an option is off the table for now, use read-only so its selection state stays legible and its value still submits with the form.

Read-only implementationCopy Anchor Link

readonly has no native effect on <input type="radio">. Pair .is-readonly with tabindex="-1" and aria-readonly="true" — the class handles the visual, pointer-events: none blocks clicks, and removing it from the tab order blocks keyboard activation:

<input type="radio" name="plan" class="nm-radio is-readonly" checked readonly tabindex="-1" aria-readonly="true">

MarkupCopy Anchor Link

Radios only behave as a mutually-exclusive set when they share the same name. Wrap the group in a <fieldset> with a <legend> so assistive tech announces what's being chosen.

Once one radio in a name group is focused, arrow keys move selection between siblings — this roving behavior is native to <input type="radio"> and needs no JavaScript.

Light & dark themeCopy Anchor Link

Both previews are locked — they don't follow the page theme switcher.

Do & don'tCopy Anchor Link

AccessibilityCopy Anchor Link

SemanticsCopy Anchor Link

• Give every radio in a group the same name — this is what makes them mutually exclusive and is what screen readers rely on to report "2 of 4," etc.
• Wrap the group in <fieldset> + <legend>, naming the question being answered ("Billing period," not "Options").

KeyboardCopy Anchor Link

• Tab moves to the group once, landing on the checked radio (or the first, if none is checked yet).
• Arrow keys move selection between radios in the same group — native browser behavior, no JavaScript required.
• Focus uses :focus-visible, so the ring appears on keyboard focus but not on mouse click.

Read-onlyCopy Anchor Link

• Native readonly has no effect on radios. Pair .is-readonly with tabindex="-1" and aria-readonly="true" so it's fully inert while its value still submits with the form.

LabelingCopy Anchor Link

• Never rely on color alone — the filled bullet is the primary signal, but make sure the label text also makes the selected option obvious out of context.

PlaygroundCopy Anchor Link

Token referenceCopy Anchor Link

ImplementationCopy Anchor Link

No JavaScript component is required — a radio group is a set of native <input> elements sharing a name, styled by CSS classes.

<link rel="stylesheet" href="namirial-theme.css">

<fieldset>
  <legend>Billing period</legend>
  <label class="nm-choice-field">
    <input type="radio" name="billing" class="nm-radio" checked>
    <span class="nm-choice-field__label">Monthly</span>
  </label>
  <label class="nm-choice-field">
    <input type="radio" name="billing" class="nm-radio">
    <span class="nm-choice-field__label">Annual</span>
  </label>
</fieldset>

CSS classesCopy Anchor Link