Radio Group

Visual Hierarchy

Place the most commonly selected or recommended option first in the list. Use descriptions beneath labels when options need additional context. Keep labels concise and parallel in grammatical structure. Consider using a default selection to reduce cognitive load when one option is clearly preferred.

Spacing & Layout

The default vertical layout uses gap-3 between items. For horizontal layouts, apply className="flex gap-4" to the RadioGroup. When including descriptions, increase spacing with className="grid gap-4" and align the radio indicator to the top using className="mt-1" on the RadioGroupItem.

Responsive Behavior

Vertical layout works well across all screen sizes. For horizontal layouts, consider switching to vertical on smaller screens using responsive classes like className="flex flex-col sm:flex-row gap-4". Radio items have a 16px (size-4) touch target for the indicator; pair with labels to expand the clickable area.

Color & Contrast

The radio indicator uses border-input for the unselected state and text-primary with fill-primary for the selected dot, ensuring clear visual differentiation. Disabled items reduce opacity to 50%. Invalid states use border-destructive with a subtle ring for form validation feedback.

Keyboard Navigation

• Tab — Move focus into and out of the radio group
• Arrow Down / Arrow Right — Move focus and selection to the next radio item
• Arrow Up / Arrow Left — Move focus and selection to the previous radio item
• Space — Select the focused radio item (if not already selected)

Screen Reader Support

• The group uses role="radiogroup" and each item uses role="radio"
• Each item announces its label, checked state, and position (e.g., "1 of 3")
• Always pair each RadioGroupItem with a <Label> using matching id/htmlFor
• Disabled items are announced as "dimmed" or "unavailable" by screen readers

Focus Management

Focus ring uses focus-visible:ring-[3px] with focus-visible:border-ring for clear visibility. Arrow keys move both focus and selection simultaneously (roving tabindex pattern). Focus wraps from the last item to the first and vice versa. Only one radio item in the group receives focus via Tab at a time.

ARIA Attributes

{/* Radio group with accessible label */}
<RadioGroup aria-label="Select a plan">
  <div className="flex items-center gap-3">
    <RadioGroupItem value="free" id="plan-free" />
    <Label htmlFor="plan-free">Free</Label>
  </div>
  <div className="flex items-center gap-3">
    <RadioGroupItem value="pro" id="plan-pro" />
    <Label htmlFor="plan-pro">Pro</Label>
  </div>
</RadioGroup>

{/* Radio group with aria-labelledby */}
<h3 id="plan-heading">Choose your plan</h3>
<RadioGroup aria-labelledby="plan-heading">
  <div className="flex items-center gap-3">
    <RadioGroupItem value="starter" id="starter" />
    <Label htmlFor="starter">Starter</Label>
  </div>
  <div className="flex items-center gap-3">
    <RadioGroupItem value="business" id="business" />
    <Label htmlFor="business">Business</Label>
  </div>
</RadioGroup>

{/* Required radio group */}
<RadioGroup required aria-label="Payment method">
  <div className="flex items-center gap-3">
    <RadioGroupItem value="card" id="pay-card" />
    <Label htmlFor="pay-card">Credit Card</Label>
  </div>
  <div className="flex items-center gap-3">
    <RadioGroupItem value="bank" id="pay-bank" />
    <Label htmlFor="pay-bank">Bank Transfer</Label>
  </div>
</RadioGroup>