APG Patterns
English GitHub
English GitHub

Radio Group

一度に1つだけチェックできるチェック可能なボタンのセット。

🤖 AI Implementation Guide

デモ

基本的な Radio Group

矢印キーを使用してナビゲートと選択を行います。Tab キーでグループの内外にフォーカスを移動します。

デフォルト値あり

defaultValue プロパティを使用した事前選択されたオプション。

無効なオプションあり

無効なオプションは、キーボードナビゲーション中にスキップされます。

水平方向

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.

アクセシビリティ

WAI-ARIA ロール

ロール 要素 説明
radiogroup コンテナ要素 ラジオボタンをグループ化します。aria-label または aria-labelledby によるアクセシブルな名前が必須です。
radio 各オプション要素 要素をラジオボタンとして識別します。グループ内で一度に1つのラジオのみが選択可能です。

この実装では、クロスブラウザでの一貫したキーボード動作のため、カスタムの role="radiogroup"role="radio" を使用しています。ネイティブの <input type="radio"> はこれらのロールを暗黙的に提供します。

WAI-ARIA ステート

aria-checked

ラジオボタンの現在のチェック状態を示します。グループ内で1つのラジオのみが aria-checked="true" を持つべきです。

true | false
必須 はい(各ラジオボタンに)
変更トリガー クリック、Space、矢印キー

aria-disabled

ラジオボタンがインタラクティブでなく、選択できないことを示します。

true(無効時のみ)
必須 いいえ(無効時のみ)
効果 矢印キーナビゲーション中はスキップされ、選択できません

WAI-ARIA プロパティ

aria-orientation

ラジオグループの方向を示します。垂直がデフォルトです。

horizontal | vertical(デフォルト)
必須 いいえ(水平方向時のみ設定)
注記 この実装では、方向に関わらずすべての矢印キーをサポートします

キーボードサポート

キー アクション
Tab グループにフォーカスを移動(選択されたラジオまたは最初のラジオへ)
Shift + Tab グループからフォーカスを移動
Space フォーカスされたラジオを選択(選択解除はしない)
Arrow Down / Right 次のラジオに移動して選択(最初にラップ)
Arrow Up / Left 前のラジオに移動して選択(最後にラップ)
Home 最初のラジオに移動して選択
End 最後のラジオに移動して選択

注記: チェックボックスとは異なり、矢印キーはフォーカス移動と選択変更の両方を行います。無効化されたラジオはナビゲーション中にスキップされます。

フォーカス管理(ローヴィングタブインデックス)

ラジオグループはローヴィングタブインデックスを使用してフォーカスを管理します。グループ内で一度に1つのラジオのみがタブ可能です:

  • 選択されたラジオtabindex="0" を持ちます
  • 何も選択されていない場合、最初の有効なラジオが tabindex="0" を持ちます
  • 他のすべてのラジオtabindex="-1" を持ちます
  • 無効なラジオ は常に tabindex="-1" を持ちます

アクセシブルな名前付け

ラジオグループと個々のラジオの両方にアクセシブルな名前が必要です:

  • ラジオグループ - コンテナに aria-label または aria-labelledby を使用します
  • 個々のラジオ - 各ラジオは aria-labelledby を介して可視テキストコンテンツでラベル付けされます
  • ネイティブの代替 - グループのラベル付けには <fieldset><legend> を使用します

ビジュアルデザイン

この実装は、状態を示すために色のみに依存しないことで WCAG 1.4.1(色の使用)に従っています:

  • 塗りつぶされた円 - 選択状態を示します
  • 空の円 - 未選択状態を示します
  • 不透明度の低下 - 無効状態を示します
  • 強制カラーモード - Windows ハイコントラストモードでのアクセシビリティのためシステムカラーを使用します

References

ソースコード

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>

使い方

使用例
<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

プロパティ デフォルト 説明
options RadioOption[] required ラジオオプションの配列
name string required フォーム送信用のグループ名
aria-label string - グループのアクセシブルラベル
aria-labelledby string - ラベル要素の ID
defaultValue string "" 初期選択値
orientation 'horizontal' | 'vertical' 'vertical' レイアウト方向
onValueChange (value: string) => void - 選択変更時のコールバック
class string - 追加 CSS クラス

RadioOption

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

テスト

テストは、キーボード操作、ARIA属性、フォーカス管理、アクセシビリティ要件全般にわたるAPG準拠を検証します。

テストカテゴリ

高優先度: APG ARIA 属性

テスト 説明
role="radiogroup" コンテナがradiogroupロールを持つ
role="radio" 各オプションがradioロールを持つ
aria-checked 選択されたラジオが aria-checked="true" を持つ
aria-disabled 無効なラジオが aria-disabled="true" を持つ
aria-orientation 水平方向時のみ設定される(垂直がデフォルト)
accessible name グループとラジオがアクセシブルな名前を持つ

高優先度: APG キーボード操作

テスト 説明
Tab focus Tabで選択されたラジオ(または何もなければ最初)にフォーカス
Tab exit Tab/Shift+Tabでグループから退出
Space select Spaceでフォーカスされたラジオを選択
Space no unselect Spaceは既に選択されたラジオの選択を解除しない
ArrowDown/Right 次へ移動して選択
ArrowUp/Left 前へ移動して選択
Home 最初へ移動して選択
End 最後へ移動して選択
Arrow wrap 最後から最初へ、またはその逆にラップ
Disabled skip ナビゲーション中に無効なラジオをスキップ

高優先度: フォーカス管理(ローヴィングタブインデックス)

テスト 説明
tabindex="0" 選択されたラジオがtabindex="0"を持つ
tabindex="-1" 非選択のラジオがtabindex="-1"を持つ
Disabled tabindex 無効なラジオがtabindex="-1"を持つ
First tabbable 何も選択されていない場合、最初の有効なラジオがタブ可能
Single tabbable グループ内で常に1つのみがtabindex="0"

中優先度: フォーム統合

テスト 説明
hidden input フォーム送信用の非表示inputが存在する
name attribute 非表示inputが正しいnameを持つ
value sync 非表示inputの値が選択を反映する

中優先度: アクセシビリティ

テスト 説明
axe violations WCAG 2.1 AA違反がない(jest-axeによる)
selected axe 選択された値での違反がない
disabled axe 無効なオプションでの違反がない

低優先度: Props と動作

テスト 説明
onValueChange 選択変更時にコールバックが発火する
defaultValue defaultValueからの初期選択
className カスタムクラスがコンテナに適用される

テストツール

詳細は testing-strategy.md (opens in new tab) を参照してください。

リソース