APG Patterns
日本語 GitHub
日本語 GitHub

Radio Group

A set of checkable buttons where only one can be checked at a time.

🤖 AI Implementation Guide

Demo

Basic Radio Group

Use arrow keys to navigate and select. Tab moves focus in/out of the group.

With Default Value

Pre-selected option using the defaultValue prop.

With Disabled Option

Disabled options are skipped during keyboard navigation.

Horizontal Orientation

Horizontal layout with orientation="horizontal".

Native HTML

Use Native HTML First

Before using this custom component, consider using native <input type="radio"> elements with <fieldset> and <legend>. They provide built-in accessibility, work without JavaScript, and require no ARIA attributes.

<fieldset>
  <legend>Favorite color</legend>
  <label><input type="radio" name="color" value="red" /> Red</label>
  <label><input type="radio" name="color" value="blue" /> Blue</label>
  <label><input type="radio" name="color" value="green" /> Green</label>
</fieldset>

Use custom implementations when you need consistent cross-browser keyboard behavior or custom styling that native elements cannot provide.

Use Case Native HTML Custom Implementation
Basic form input Recommended Not needed
JavaScript disabled support Works natively Requires fallback
Arrow key navigation Browser-dependent* Consistent behavior
Custom styling Limited (browser-dependent) Full control
Form submission Built-in Requires hidden input

*Native radio keyboard behavior varies between browsers. Some browsers may not support all APG keyboard interactions (like Home/End) out of the box.

Accessibility Features

WAI-ARIA Roles

Role Element Description
radiogroup Container element Groups radio buttons together. Must have an accessible name via aria-label or aria-labelledby.
radio Each option element Identifies the element as a radio button. Only one radio in a group can be checked at a time.

This implementation uses custom role="radiogroup" and role="radio" for consistent cross-browser keyboard behavior. Native <input type="radio"> provides these roles implicitly.

WAI-ARIA States

aria-checked

Indicates the current checked state of the radio button. Only one radio in a group should have aria-checked="true".

Values true | false
Required Yes (on each radio)
Change Trigger Click, Space, Arrow keys

aria-disabled

Indicates that the radio button is not interactive and cannot be selected.

Values true (only when disabled)
Required No (only when disabled)
Effect Skipped during arrow key navigation, cannot be selected

WAI-ARIA Properties

aria-orientation

Indicates the orientation of the radio group. Vertical is the default.

Values horizontal | vertical (default)
Required No (only set when horizontal)
Note This implementation supports all arrow keys regardless of orientation

Keyboard Support

Key Action
Tab Move focus into the group (to selected or first radio)
Shift + Tab Move focus out of the group
Space Select the focused radio (does not unselect)
Arrow Down / Right Move to next radio and select (wraps to first)
Arrow Up / Left Move to previous radio and select (wraps to last)
Home Move to first radio and select
End Move to last radio and select

Note: Unlike Checkbox, arrow keys both move focus AND change selection. Disabled radios are skipped during navigation.

Focus Management (Roving Tabindex)

Radio groups use roving tabindex to manage focus. Only one radio in the group is tabbable at any time:

  • Selected radio has tabindex="0"
  • If none selected, first enabled radio has tabindex="0"
  • All other radios have tabindex="-1"
  • Disabled radios always have tabindex="-1"

Accessible Naming

Both the radio group and individual radios must have accessible names:

  • Radio group - Use aria-label or aria-labelledby on the container
  • Individual radios - Each radio is labeled by its visible text content via aria-labelledby
  • Native alternative - Use <fieldset> with <legend> for group labeling

Visual Design

This implementation follows WCAG 1.4.1 (Use of Color) by not relying solely on color to indicate state:

  • Filled circle - Indicates selected state
  • Empty circle - Indicates unselected state
  • Reduced opacity - Indicates disabled state
  • Forced colors mode - Uses system colors for accessibility in Windows High Contrast Mode

References

Source Code

RadioGroup.svelte
<script lang="ts">
  import { untrack } from 'svelte';

  interface RadioOption {
    id: string;
    label: string;
    value: string;
    disabled?: boolean;
  }

  interface RadioGroupProps {
    options: RadioOption[];
    name: string;
    'aria-label'?: string;
    'aria-labelledby'?: string;
    defaultValue?: string;
    orientation?: 'horizontal' | 'vertical';
    onValueChange?: (value: string) => void;
    class?: string;
  }

  let {
    options,
    name,
    'aria-label': ariaLabel,
    'aria-labelledby': ariaLabelledby,
    defaultValue = '',
    orientation = 'vertical',
    onValueChange = (_) => {},
    class: className,
  }: RadioGroupProps = $props();

  // Generate unique ID
  const instanceId = `radio-group-${Math.random().toString(36).slice(2, 9)}`;

  // Get enabled options
  function getEnabledOptions() {
    return options.filter((opt) => !opt.disabled);
  }

  // Find initial value
  function getInitialValue() {
    if (defaultValue) {
      const option = options.find((opt) => opt.value === defaultValue);
      if (option && !option.disabled) {
        return defaultValue;
      }
    }
    return '';
  }

  let selectedValue = $state(untrack(() => getInitialValue()));

  // Refs for focus management
  let radioRefs: Map<string, HTMLDivElement> = new Map();

  function radioRefAction(node: HTMLDivElement, value: string) {
    radioRefs.set(value, node);
    return {
      destroy() {
        radioRefs.delete(value);
      },
    };
  }

  // Get the tabbable radio value
  function getTabbableValue() {
    const enabledOptions = getEnabledOptions();
    if (selectedValue && enabledOptions.some((opt) => opt.value === selectedValue)) {
      return selectedValue;
    }
    return enabledOptions[0]?.value || '';
  }

  function getTabIndex(option: RadioOption): number {
    if (option.disabled) return -1;
    return option.value === getTabbableValue() ? 0 : -1;
  }

  // Focus a radio by value
  function focusRadio(value: string) {
    const radioEl = radioRefs.get(value);
    radioEl?.focus();
  }

  // Select a radio
  function selectRadio(value: string) {
    const option = options.find((opt) => opt.value === value);
    if (option && !option.disabled) {
      selectedValue = value;
      onValueChange(value);
    }
  }

  // Get enabled index of a value
  function getEnabledIndex(value: string) {
    return getEnabledOptions().findIndex((opt) => opt.value === value);
  }

  // Navigate and select
  function navigateAndSelect(direction: 'next' | 'prev' | 'first' | 'last', currentValue: string) {
    const enabledOptions = getEnabledOptions();
    if (enabledOptions.length === 0) return;

    let targetIndex: number;
    const currentIndex = getEnabledIndex(currentValue);

    switch (direction) {
      case 'next':
        targetIndex = currentIndex >= 0 ? (currentIndex + 1) % enabledOptions.length : 0;
        break;
      case 'prev':
        targetIndex =
          currentIndex >= 0
            ? (currentIndex - 1 + enabledOptions.length) % enabledOptions.length
            : enabledOptions.length - 1;
        break;
      case 'first':
        targetIndex = 0;
        break;
      case 'last':
        targetIndex = enabledOptions.length - 1;
        break;
    }

    const targetOption = enabledOptions[targetIndex];
    if (targetOption) {
      focusRadio(targetOption.value);
      selectRadio(targetOption.value);
    }
  }

  function handleKeyDown(event: KeyboardEvent, optionValue: string) {
    const { key } = event;

    switch (key) {
      case 'ArrowDown':
      case 'ArrowRight':
        event.preventDefault();
        navigateAndSelect('next', optionValue);
        break;

      case 'ArrowUp':
      case 'ArrowLeft':
        event.preventDefault();
        navigateAndSelect('prev', optionValue);
        break;

      case 'Home':
        event.preventDefault();
        navigateAndSelect('first', optionValue);
        break;

      case 'End':
        event.preventDefault();
        navigateAndSelect('last', optionValue);
        break;

      case ' ':
        event.preventDefault();
        selectRadio(optionValue);
        break;
    }
  }

  function handleClick(option: RadioOption) {
    if (!option.disabled) {
      focusRadio(option.value);
      selectRadio(option.value);
    }
  }
</script>

<div
  role="radiogroup"
  aria-label={ariaLabel}
  aria-labelledby={ariaLabelledby}
  aria-orientation={orientation === 'horizontal' ? 'horizontal' : undefined}
  class="apg-radio-group {className || ''}"
>
  <!-- Hidden input for form submission -->
  <input type="hidden" {name} value={selectedValue} />

  {#each options as option (option.id)}
    <div
      use:radioRefAction={option.value}
      role="radio"
      aria-checked={selectedValue === option.value}
      aria-disabled={option.disabled || undefined}
      aria-labelledby={`${instanceId}-label-${option.id}`}
      tabindex={getTabIndex(option)}
      class="apg-radio {selectedValue === option.value
        ? 'apg-radio--selected'
        : ''} {option.disabled ? 'apg-radio--disabled' : ''}"
      onclick={() => handleClick(option)}
      onkeydown={(e) => handleKeyDown(e, option.value)}
    >
      <span class="apg-radio-control" aria-hidden="true">
        <span class="apg-radio-indicator"></span>
      </span>
      <span id={`${instanceId}-label-${option.id}`} class="apg-radio-label">
        {option.label}
      </span>
    </div>
  {/each}
</div>

Usage

Example
<script>
  import RadioGroup from './RadioGroup.svelte';

  const options = [
    { id: 'red', label: 'Red', value: 'red' },
    { id: 'blue', label: 'Blue', value: 'blue' },
    { id: 'green', label: 'Green', value: 'green' },
  ];

  function handleChange(value) {
    console.log('Selected:', value);
  }
</script>

<RadioGroup
  {options}
  name="color"
  aria-label="Favorite color"
  defaultValue="blue"
  onValueChange={handleChange}
/>

API

RadioGroupProps

Prop Type Default Description
options RadioOption[] required Array of radio options
name string required Group name for form submission
aria-label string - Accessible label for the group
aria-labelledby string - ID of labeling element
defaultValue string "" Initially selected value
orientation 'horizontal' | 'vertical' 'vertical' Layout orientation
onValueChange (value: string) => void - Callback when selection changes
class string - Additional CSS class

RadioOption

Types
interface RadioOption {
  id: string;
  label: string;
  value: string;
  disabled?: boolean;
}

Testing

Tests verify APG compliance across keyboard interaction, ARIA attributes, focus management, and accessibility requirements.

Test Categories

High Priority: APG ARIA Attributes

Test Description
role="radiogroup" Container has radiogroup role
role="radio" Each option has radio role
aria-checked Selected radio has aria-checked="true"
aria-disabled Disabled radios have aria-disabled="true"
aria-orientation Only set when horizontal (vertical is default)
accessible name Group and radios have accessible names

High Priority: APG Keyboard Interaction

Test Description
Tab focus Tab focuses selected radio (or first if none)
Tab exit Tab/Shift+Tab exits the group
Space select Space selects focused radio
Space no unselect Space does not unselect already selected radio
ArrowDown/Right Moves to next and selects
ArrowUp/Left Moves to previous and selects
Home Moves to first and selects
End Moves to last and selects
Arrow wrap Wraps from last to first and vice versa
Disabled skip Disabled radios skipped during navigation

High Priority: Focus Management (Roving Tabindex)

Test Description
tabindex="0" Selected radio has tabindex="0"
tabindex="-1" Non-selected radios have tabindex="-1"
Disabled tabindex Disabled radios have tabindex="-1"
First tabbable First enabled radio tabbable when none selected
Single tabbable Only one tabindex="0" in group at any time

Medium Priority: Form Integration

Test Description
hidden input Hidden input exists for form submission
name attribute Hidden input has correct name
value sync Hidden input value reflects selection

Medium Priority: Accessibility

Test Description
axe violations No WCAG 2.1 AA violations (via jest-axe)
selected axe No violations with selected value
disabled axe No violations with disabled option

Low Priority: Props & Behavior

Test Description
onValueChange Callback fires on selection change
defaultValue Initial selection from defaultValue
className Custom class applied to container

Testing Tools

See testing-strategy.md (opens in new tab) for full documentation.

Resources