Radio Group

Radio Group presents a short set of mutually exclusive options. Use it when every option can be understood without opening another surface and choosing one value is required to continue or configure the current task.

View density

Default

Comfortable

Compact

InstallTerminal

npm install @a3s-lab/ui@0.4.0

<fieldset class="fieldset">
  <legend data-variant="label">View density</legend>
  <div class="grid gap-3">
    <div class="field" data-orientation="horizontal">
      <input
        class="input"
        type="radio"
        id="density-default"
        name="density"
        value="default"
      />
      <label for="density-default">Default</label>
    </div>
    <div class="field" data-orientation="horizontal">
      <input
        class="input"
        type="radio"
        id="density-compact"
        name="density"
        value="compact"
        checked
      />
      <label for="density-compact">Compact</label>
    </div>
  </div>
</fieldset>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

Usage

Import Tailwind and the complete A3S style bundle:

@import "tailwindcss";
@import "@a3s-lab/ui/a3s.css";

Give related native radio inputs the same name. Associate every input with a visible label, then give the complete group one accessible name through fieldset and legend or role="radiogroup" and aria-labelledby.

<fieldset class="fieldset">
  <legend data-variant="label">View density</legend>
  <div class="grid gap-3">
    <div class="field" data-orientation="horizontal">
      <input
        class="input"
        type="radio"
        id="density-default"
        name="density"
        value="default"
      />
      <label for="density-default">Default</label>
    </div>
    <div class="field" data-orientation="horizontal">
      <input
        class="input"
        type="radio"
        id="density-compact"
        name="density"
        value="compact"
        checked
      />
      <label for="density-compact">Compact</label>
    </div>
  </div>
</fieldset>

For component-level loading, import the base styles, Radio structure, Field structure, and the A3S visual style in that order. See Installation for CDN and other integrations.

@import "@a3s-lab/ui/base.css";
@import "@a3s-lab/ui/components/radio.css";
@import "@a3s-lab/ui/components/field.css";
@import "@a3s-lab/ui/styles/a3s.css";

Parameters

Parameter	Value	Purpose
Group	`<fieldset>` or `role="radiogroup"`	Gives the related choices one semantic boundary and name
Root class	`radio-group`	Applies the stable group layout and framework-adapter contract
Root option	`<input type="radio">`	Preserves native form, validation, keyboard, and accessibility behavior
`class`	`input`	Applies Radio structure and visual styles
`name`	Shared string	Makes the options mutually exclusive and submits one value
`value`	Stable string	Provides the submitted application value; do not derive it from visible copy
`checked`	Boolean attribute	Marks the actual initial selection; omit it when the user must make a choice
`disabled`	Boolean attribute	Prevents selection; explain why the option is unavailable
`required`	Boolean attribute	Requires one option in the named native group before form submission
`aria-invalid`	`true`	Exposes a failed validation state after validation has run
`aria-describedby`	Element ID	Associates constraints, consequences, or recovery guidance

States and variants

Unchecked and checked are the normal interactive states. Arrow keys move selection inside the focused native group; Tab enters and leaves the group as a single stop. Disabled and invalid appearances are meaningful only when the surrounding content explains the constraint or recovery.

With descriptions

The label names the option. Supporting copy explains the effect of choosing it and remains outside the label so assistive technology does not repeat a long description as the option name.

View density

Default

Balanced spacing for everyday work.

Comfortable

Larger targets and more separation between rows.

Compact

More rows on screen with tighter visual spacing.

<div
    role="radiogroup"
    aria-labelledby="density-description-label-en"
    class="radio-group w-fit"
  >
    <span id="density-description-label-en" class="label">
      View density
    </span>
    <div class="field" data-orientation="horizontal">
      <input
        type="radio"
        id="desc-r1"
        name="radio-description"
        value="default"
        class="input"
        aria-describedby="desc-r1-copy"
      />
      <section>
        <label for="desc-r1">Default</label>
        <p id="desc-r1-copy">Balanced spacing for everyday work.</p>
      </section>
    </div>
    <div class="field" data-orientation="horizontal">
      <input
        type="radio"
        id="desc-r2"
        name="radio-description"
        value="comfortable"
        class="input"
        aria-describedby="desc-r2-copy"
        defaultChecked
      />
      <section>
        <label for="desc-r2">Comfortable</label>
        <p id="desc-r2-copy">
          Larger targets and more separation between rows.
        </p>
      </section>
    </div>
    <div class="field" data-orientation="horizontal">
      <input
        type="radio"
        id="desc-r3"
        name="radio-description"
        value="compact"
        class="input"
        aria-describedby="desc-r3-copy"
      />
      <section>
        <label for="desc-r3">Compact</label>
        <p id="desc-r3-copy">
          More rows on screen with tighter visual spacing.
        </p>
      </section>
    </div>
  </div>

Choice cards

Use choice cards only when each option needs a title and consequence. data-variant="choice-card" expands the visible option label across the complete field, so the whole card remains one native radio target without invalid nested markup or a second group role. The associated <label> supplies the accessible name; aria-describedby adds the consequence without repeating it as part of that name.

Workspace plan

Plus

For individuals and small teams.

Pro

Adds team controls and a shared audit history.

Enterprise

Adds organization policy and managed access.

<div
    role="radiogroup"
    aria-labelledby="plan-label-en"
    class="radio-group w-full max-w-md"
  >
    <span id="plan-label-en" class="label">
      Workspace plan
    </span>
    <div class="field" data-orientation="horizontal" data-variant="choice-card">
      <section>
        <label for="plus-plan">Plus</label>
        <p id="plus-plan-description">For individuals and small teams.</p>
      </section>
      <input
        type="radio"
        id="plus-plan"
        name="choice-plan"
        value="plus"
        class="input"
        aria-describedby="plus-plan-description"
        defaultChecked
      />
    </div>
    <div class="field" data-orientation="horizontal" data-variant="choice-card">
      <section>
        <label for="pro-plan">Pro</label>
        <p id="pro-plan-description">
          Adds team controls and a shared audit history.
        </p>
      </section>
      <input
        type="radio"
        id="pro-plan"
        name="choice-plan"
        value="pro"
        class="input"
        aria-describedby="pro-plan-description"
      />
    </div>
    <div class="field" data-orientation="horizontal" data-variant="choice-card">
      <section>
        <label for="enterprise-plan">Enterprise</label>
        <p id="enterprise-plan-description">
          Adds organization policy and managed access.
        </p>
      </section>
      <input
        type="radio"
        id="enterprise-plan"
        name="choice-plan"
        value="enterprise"
        class="input"
        aria-describedby="enterprise-plan-description"
      />
    </div>
  </div>

Fieldset

Prefer fieldset and legend for form questions. The legend supplies the group name, so do not add a nested radiogroup with the same label.

Subscription plan

Yearly billing saves two monthly payments.

Monthly ($9.99/month)

Yearly ($99.99/year)

Lifetime ($299.99)

<fieldset class="fieldset">
    <legend data-variant="label">Subscription plan</legend>
    <p id="subscription-help-en">Yearly billing saves two monthly payments.</p>
    <div class="grid gap-3">
      <div class="field" data-orientation="horizontal">
        <input
          type="radio"
          id="plan-monthly"
          name="subscription-plan"
          value="monthly"
          class="input"
          aria-describedby="subscription-help-en"
          defaultChecked
        />
        <label for="plan-monthly">Monthly ($9.99/month)</label>
      </div>
      <div class="field" data-orientation="horizontal">
        <input
          type="radio"
          id="plan-yearly"
          name="subscription-plan"
          value="yearly"
          class="input"
          aria-describedby="subscription-help-en"
        />
        <label for="plan-yearly">Yearly ($99.99/year)</label>
      </div>
      <div class="field" data-orientation="horizontal">
        <input
          type="radio"
          id="plan-lifetime"
          name="subscription-plan"
          value="lifetime"
          class="input"
          aria-describedby="subscription-help-en"
        />
        <label for="plan-lifetime">Lifetime ($299.99)</label>
      </div>
    </div>
  </fieldset>

Disabled option

Disable only the unavailable option, preserve the other choices, and put the reason next to the disabled control.

Execution environment

Accelerated

No compatible device is connected.

Standard

Remote

<div
    role="radiogroup"
    aria-labelledby="availability-label-en"
    class="radio-group w-fit"
  >
    <span id="availability-label-en" class="label">
      Execution environment
    </span>
    <div class="field" data-orientation="horizontal" data-disabled>
      <input
        type="radio"
        id="disabled-1"
        name="radio-disabled"
        value="accelerated"
        class="input"
        aria-describedby="disabled-1-reason"
        disabled
      />
      <section>
        <label for="disabled-1">Accelerated</label>
        <p id="disabled-1-reason">No compatible device is connected.</p>
      </section>
    </div>
    <div class="field" data-orientation="horizontal">
      <input
        type="radio"
        id="disabled-2"
        name="radio-disabled"
        value="standard"
        class="input"
        defaultChecked
      />
      <label for="disabled-2">Standard</label>
    </div>
    <div class="field" data-orientation="horizontal">
      <input
        type="radio"
        id="disabled-3"
        name="radio-disabled"
        value="remote"
        class="input"
      />
      <label for="disabled-3">Remote</label>
    </div>
  </div>

Invalid

Do not mark a valid preselected value as an error. Start without an error, validate only after an attempted continuation, focus the first option when the group is still empty, and clear stale error semantics as soon as the user recovers or resets the form.

<form
    class="grid gap-4"
    data-radio-group-validation-demo="en"
    novalidate
    onsubmit="event.preventDefault(); const group = this.querySelector('fieldset'); const options = [...group.querySelectorAll('input[type=radio]')]; if (options.some((option) => option.checked)) return; group.setAttribute('data-invalid', ''); options.forEach((option) => option.setAttribute('aria-invalid', 'true')); group.querySelector('[role=alert]').hidden = false; options[0].focus();"
    onreset="const group = this.querySelector('fieldset'); group.removeAttribute('data-invalid'); group.querySelectorAll('[aria-invalid=true]').forEach((option) => option.removeAttribute('aria-invalid')); group.querySelector('[role=alert]').hidden = true;"
  >
    <fieldset
      class="fieldset"
      onchange="if (!event.target.matches('input[type=radio]')) return; this.removeAttribute('data-invalid'); this.querySelectorAll('[aria-invalid=true]').forEach((option) => option.removeAttribute('aria-invalid')); this.querySelector('[role=alert]').hidden = true;"
    >
      <legend data-variant="label">Notification preference</legend>
      <p
        id="notification-preference-error-en"
        class="text-destructive"
        role="alert"
        hidden
      >
        Choose one delivery method before continuing.
      </p>
      <div class="grid gap-3">
        <div class="field" data-orientation="horizontal">
          <input
            type="radio"
            id="invalid-email"
            name="notification-preference"
            value="email"
            class="input"
            required
            aria-describedby="notification-preference-error-en"
          />
          <label for="invalid-email">Email only</label>
        </div>
        <div class="field" data-orientation="horizontal">
          <input
            type="radio"
            id="invalid-sms"
            name="notification-preference"
            value="sms"
            class="input"
            required
            aria-describedby="notification-preference-error-en"
          />
          <label for="invalid-sms">Text message only</label>
        </div>
        <div class="field" data-orientation="horizontal">
          <input
            type="radio"
            id="invalid-both"
            name="notification-preference"
            value="both"
            class="input"
            required
            aria-describedby="notification-preference-error-en"
          />
          <label for="invalid-both">Email and text message</label>
        </div>
      </div>
    </fieldset>
    <div class="flex flex-wrap gap-2">
      <button id="notification-preference-submit-en" type="submit" class="btn">
        Continue
      </button>
      <button
        id="notification-preference-reset-en"
        type="reset"
        class="btn"
        data-variant="outline"
      >
        Reset
      </button>
    </div>
  </form>

RTL

Set dir="rtl" on the group or an ancestor. Native radio keyboard behavior follows the document direction, while the option order remains the meaningful DOM order.

كثافة العرض

افتراضي

تباعد قياسي لمعظم حالات الاستخدام.

مريح

مساحة أكبر بين العناصر.

مضغوط

تباعد أدنى للتخطيطات الكثيفة.

<div
    dir="rtl"
    role="radiogroup"
    aria-labelledby="density-label-rtl"
    class="radio-group w-fit"
  >
    <span id="density-label-rtl" class="label">
      كثافة العرض
    </span>
    <div class="field" data-orientation="horizontal">
      <input
        type="radio"
        id="r1-rtl"
        name="radio-rtl"
        value="default"
        class="input"
      />
      <section>
        <label for="r1-rtl">افتراضي</label>
        <p>تباعد قياسي لمعظم حالات الاستخدام.</p>
      </section>
    </div>
    <div class="field" data-orientation="horizontal">
      <input
        type="radio"
        id="r2-rtl"
        name="radio-rtl"
        value="comfortable"
        class="input"
        defaultChecked
      />
      <section>
        <label for="r2-rtl">مريح</label>
        <p>مساحة أكبر بين العناصر.</p>
      </section>
    </div>
    <div class="field" data-orientation="horizontal">
      <input
        type="radio"
        id="r3-rtl"
        name="radio-rtl"
        value="compact"
        class="input"
      />
      <section>
        <label for="r3-rtl">مضغوط</label>
        <p>تباعد أدنى للتخطيطات الكثيفة.</p>
      </section>
    </div>
  </div>

Accessibility

Give the complete group one concise accessible name. Prefer fieldset and legend in forms; otherwise use role="radiogroup" with aria-labelledby or aria-label.
Give every radio a visible label and one stable submitted value. A description belongs in aria-describedby, not inside an excessively long accessible name.
Use one shared name for mutually exclusive options. Do not simulate exclusivity with independent buttons or application-only state.
Keep native arrow-key behavior. Tab enters the selected radio, arrows move and select, and Tab leaves the group; do not create a separate Tab stop for every option.
Do not add role="group" to every option row. The radiogroup or fieldset is the only group boundary.
Set disabled on only the unavailable option and keep its reason visible. If all choices are unavailable, disable the owning form action and explain the blocking condition.
Show an invalid state only after validation runs. Use required, aria-invalid="true", and aria-describedby to connect a recovery-oriented error; clear stale error attributes and text when a valid option is chosen or the form is reset.
Keep the full radio hit target at least 44px on coarse pointers even though the visible indicator remains compact.

#Radio Group

#Usage

#Parameters

#States and variants

#With descriptions

#Choice cards

#Fieldset

#Disabled option

#Invalid

#RTL

#Accessibility