Radio group

Live variants

default

Default layout

Split horizontally Stacked Tabbed

✕ Choose a layout.

Markup

<j3w1-radio-group id="example-radio-group-default"><fieldset class="radio-group" aria-describedby="example-radio-group-default-rg-layout-message">
  <legend class="radio-group-legend">Default layout <span class="radio-group-required" aria-hidden="true">*</span><span class="radio-group-required sr-only"> required</span></legend>
  <div class="radio-group-options">
    <label class="radio-group-option">
      <span class="radio-group-control">
        <input class="radio-group-input" type="radio" name="example-radio-group-default-layout" value="split">
        <span class="radio-group-dot" aria-hidden="true"></span>
      </span>
      <span class="radio-group-text">Split horizontally</span>
    </label>
    <label class="radio-group-option">
      <span class="radio-group-control">
        <input class="radio-group-input" type="radio" name="example-radio-group-default-layout" value="stacked">
        <span class="radio-group-dot" aria-hidden="true"></span>
      </span>
      <span class="radio-group-text">Stacked</span>
    </label>
    <label class="radio-group-option">
      <span class="radio-group-control">
        <input class="radio-group-input" type="radio" name="example-radio-group-default-layout" value="tabbed">
        <span class="radio-group-dot" aria-hidden="true"></span>
      </span>
      <span class="radio-group-text">Tabbed</span>
    </label>
  </div>
  <p class="radio-group-message" id="example-radio-group-default-rg-layout-message">✕ Choose a layout.</p>
</fieldset></j3w1-radio-group>

horizontal

Density

Compact Comfortable

✕ Choose a density.

Markup

<j3w1-radio-group id="example-radio-group-horizontal"><fieldset class="radio-group radio-group-horizontal" aria-describedby="example-radio-group-horizontal-rg-density-message">
  <legend class="radio-group-legend">Density <span class="radio-group-required" aria-hidden="true">*</span><span class="radio-group-required sr-only"> required</span></legend>
  <div class="radio-group-options">
    <label class="radio-group-option">
      <span class="radio-group-control">
        <input class="radio-group-input" type="radio" name="example-radio-group-horizontal-density" value="compact">
        <span class="radio-group-dot" aria-hidden="true"></span>
      </span>
      <span class="radio-group-text">Compact</span>
    </label>
    <label class="radio-group-option">
      <span class="radio-group-control">
        <input class="radio-group-input" type="radio" name="example-radio-group-horizontal-density" value="comfortable">
        <span class="radio-group-dot" aria-hidden="true"></span>
      </span>
      <span class="radio-group-text">Comfortable</span>
    </label>
  </div>
  <p class="radio-group-message" id="example-radio-group-horizontal-rg-density-message">✕ Choose a density.</p>
</fieldset></j3w1-radio-group>

Install and register

Use the exact version. If npm publication is pending, install the release tarball from the installation guide.

npm install --save-exact @j3w1/ui@4.0.0

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/radio-group.css';
import '@j3w1/ui/register/radio-group';

Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@4.0.0 j3w1-ui copy radio-group --out ./vendor/j3w1/radio-group

The CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.

Public API

attributes

Name	Type / signature	Meaning
`disabled`	`CustomEvent`	Disable the native controls owned by this instance.
`loading`	`CustomEvent`	Mark the primary control busy and prevent duplicate activation.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.

events

Name	Type / signature	Meaning

Dependencies and verification

Registered components: none. Style dependencies: none.

Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.

Full implementation manifest, API and token dependency closure

Canonical specification

Specimen density

Specimen profile

Radio group `radio-group`

Family: Basic forms
Maturity: stable
Priority: R1
Since: 0.1.0
Native control: native <input type="radio"> inside <fieldset> with <legend> — APG pattern
specified
demonstrated
test implemented

A fieldset of native radios for one exclusive choice; each radio is a 16px square that fills with the primary action colour and an inner square when checked.

Report an issue with this component

Tokens

Focus a role to inspect its values; follow its link for persistent usage and source details.

Part	Role	Value	Use
`box.bg`	`color.surface.input`approveduse	`#000000`	Form-control fill.
`box.border`	`color.border.control`approveduse	`#c81a1a`	D-041 owner correction: red control and floating-frame borders, distinct from rose text.
`box.bg-hover`	`color.interaction.hover.bg`approveduse	`#1c1010`	D-041 interaction.hover.bg: color.primitive.modern.hover.
`box.ring`	`color.interaction.focus.ring`observeduse	`#e53935`	1px dashed focus ring on controls and rows.
`box.bg-checked`	`color.action.primary.bg`approveduse	`#7d1310`	Primary button fill; D-026 darkened it off color12, which stays fixed as heritage ANSI 12.
`box.bg-checked-hover`	`color.action.primary.hover-bg`observeduse	`#911410`	Primary button hover; pair with action.primary.text (D-033).
`box.dot`	`color.action.primary.text`approveduse	`#ffa2a7`	Primary action labels: bright rose across rest, hover and pressed states (D-033).
`box.ring-checked`	`color.interaction.focus.ring-container`observeduse	`#ffa2a7`	Focus colour for containers and explicitly mapped filled controls (D-015); component rules determine ring geometry.
`box.border-invalid`	`color.status.danger.border`observeduse	`#e53935`	Danger border, 2px on invalid inputs.
`box.bg-disabled`	`color.interaction.disabled.bg`approveduse	`#0d0707`	D-041 interaction.disabled.bg: color.primitive.modern.panel.
`box.border-disabled`	`color.border.disabled`approveduse	`#482b2b`	D-041 border.disabled: color.primitive.modern.divider.
`box.dot-disabled`	`color.text.disabled`approveduse	`#a3676b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`text.default`	`color.text.default`approveduse	`#e99499`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`text.disabled`	`color.text.disabled`approveduse	`#a3676b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`legend.text`	`color.text.bright`approveduse	`#ffa2a7`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`legend.required-mark`	`color.status.danger.text`observeduse	`#f07178`	D-041 readable error text on neutral surfaces and native warning tints.
`message.text`	`color.status.danger.text`observeduse	`#f07178`	D-041 readable error text on neutral surfaces and native warning tints.

State matrix

Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).

State	Vertical	Horizontal
`default`	Default layout required Split horizontally Stacked Tabbed ✕ Choose a layout.	Density required Compact Comfortable ✕ Choose a density.
`hover`
`focus-visible`
`checked`
`checked+focus-visible`
`disabled`
`invalid`
`required`

Purpose

One choice among two to roughly six visible options; fewer is a checkbox or switch, more a select. It differs from a checkbox by the inner square instead of ✓ and by arrow keys instead of separate tab stops.

Anatomy

Parts as listed in the anatomy.

States

State	Visual	Non-colour channel
default	16px square, 1px `color.border.control` on `color.surface.input`; text `color.text.default`	—
hover	box → `color.interaction.hover.bg`; a checked box → `color.action.primary.hover-bg`	cursor: pointer; hover-capable pointers only
focus-visible	1px dashed `color.interaction.focus.ring` ring at −2px around the box	the ring
checked	box fills `color.action.primary.bg`; 8px inner square in `color.action.primary.text`; border stays `color.border.control`	the inner square; `checked`
checked+focus-visible	the fill and a ring in `color.interaction.focus.ring-container`	inner square and ring
disabled	boxes `color.interaction.disabled.bg`, 1px `color.border.disabled`; inner square and text `color.text.disabled`	`disabled`; cursor: not-allowed
invalid	every box border 2px `color.status.danger.border`; message with the ✕ glyph	border width 1 → 2px; glyph; `aria-invalid`
required	`*` after the legend in `color.status.danger.text` plus visually hidden “required”	`required`; the mark

Precedence: disabled > invalid > checked > hover; focus-visible is always drawn.

Keyboard

Native and one tab stop. Arrows move focus and the check together, so a radio group never navigates or sends a request on change; the value is read on submit or through an explicit action.

Accessibility

The legend names the group and is read before each option. aria-invalid is set on the inputs after submit. A group with no default checked radio has a required mark or a “none” option, so the empty state is intentional. Text meets 4.5:1; box edges, the inner square and rings 3:1.

Portability

Square, border, fill and one inner square; no pseudo-element. A host that insists on a circular indicator records the deviation instead of replacing the control with a custom widget.

Non-examples

Circular radios. Checked shown by border colour alone, without the inner square. Submitting or navigating on change. No legend, or the legend as one option’s label. A tab stop per radio. A lone radio. Disabling by opacity. A div with role="radiogroup" built from spans.

Contrast report

17 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.

Pair	State	Kind	Foreground	Background	Ratio	Min	Result
radio-group default border	default	ui	`color.border.control` `#c81a1a`	`color.surface.input` `#000000`	3.62	3	pass
radio-group hover border	hover	ui	`color.border.control` `#c81a1a`	`color.interaction.hover.bg` `#1c1010`	3.20	3	pass
radio-group focus-visible border	focus-visible	ui	`color.border.control` `#c81a1a`	`color.surface.input` `#000000`	3.62	3	pass
radio-group focus-visible outline	focus-visible	ui	`color.interaction.focus.ring` `#e53935`	`color.surface.input` `#000000`	4.97	3	pass
radio-group checked text	checked	text	`color.action.primary.text` `#ffa2a7`	`color.action.primary.bg` `#7d1310`	5.57	4.5	pass
radio-group checked+focus-visible text	checked+focus-visible	text	`color.action.primary.text` `#ffa2a7`	`color.action.primary.bg` `#7d1310`	5.57	4.5	pass
radio-group checked+focus-visible outline	checked+focus-visible	ui	`color.interaction.focus.ring-container` `#ffa2a7`	`color.action.primary.bg` `#7d1310`	5.57	3	pass
radio-group invalid border	invalid	ui	`color.status.danger.border` `#e53935`	`color.surface.input` `#000000`	4.97	3	pass
radio-group required border	required	ui	`color.border.control` `#c81a1a`	`color.surface.input` `#000000`	3.62	3	pass
option text on the panel surface	—	text	`color.text.default` `#e99499`	`color.surface.default` `#0d0707`	8.72	4.5	pass
legend on the panel surface	—	text	`color.text.bright` `#ffa2a7`	`color.surface.default` `#0d0707`	10.45	4.5	pass
checked radio edge against the panel (the border stays border.control)	checked	ui	`color.border.control` `#c81a1a`	`color.surface.default` `#0d0707`	3.44	3	pass
inner square on the hovered checked fill	hover	ui	`color.action.primary.text` `#ffa2a7`	`color.action.primary.hover-bg` `#911410`	4.75	3	pass
validation message on the panel surface	—	text	`color.status.danger.text` `#f07178`	`color.surface.default` `#0d0707`	6.98	4.5	pass
disabled option text (exempt; house floor 3:1)	disabled	ui	`color.text.disabled` `#a3676b`	`color.surface.default` `#0d0707`	4.48	3	pass
disabled inner square (exempt; house floor 3:1)	disabled	ui	`color.text.disabled` `#a3676b`	`color.interaction.disabled.bg` `#0d0707`	4.48	3	pass
disabled border (exempt)	disabled	ui	`color.border.disabled` `#482b2b`	`color.interaction.disabled.bg` `#0d0707`	1.58	1	pass

Keys

Key	Action
`Tab / Shift+Tab`	Enters the group on the checked radio, or the first when none is checked; leaves it entirely.
`Up / Down / Left / Right`	Moves the check to the previous or next radio and selects it (native); wraps at the ends.
`Space`	Checks the focused radio when none is checked.

For agents

Component JSON ·Implementation brief ·Build a task kit ·

Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-TOUCH FX-DENSITY FX-STATE-MATRIX

j3w1 / theme

j3w1 / command

Live variants

default

horizontal

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Radio group `radio-group`

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Live variants

default

horizontal

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Radio group radio-group

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Radio group `radio-group`