React Toast通知システムの実装ガイド：useState・useRefでアクセシビリティ対応の通知UIを作成する方法

背景

正直なところ、最初は静的なエラー表示で問題ないと思っていましたが、実際に使ってみるとユーザー体験の悪さに気づきました。

エラーメッセージの表示方法が静的な赤枠表示だったため、ユーザー体験が悪かったです。

重大度に応じた色分け、自動消去、アクションボタン対応のToast通知システムに改善する必要がありました。

こんな人におすすめ

この記事は以下のような方に役立ちます。

• ReactでToast通知システムを実装したい方
• 重大度別の色分けや自動消去タイマーを実装したい方
• useRefによるタイマー管理やメモリリーク防止を学びたい方
• アクセシビリティ（WCAG AA準拠）を考慮したUIを実装したい方
• 既存コードの後方互換性を維持しながら機能を追加したい方

目次

• 背景
• こんな人におすすめ
• 要件
• 実装方針
• ポイント
  • 1. useRefでタイマー管理（メモリリーク防止）
  • 2. 重複Toast防止オプション
  • 3. アクセシビリティ対応
  • 4. 後方互換性
• この改善の良かった点
• 学び
• 確認手順
• FAQ：よくある質問
• まとめ

要件

flowchart LR
    subgraph 重大度別の振る舞い
        S[success/info]
        W[warning]
        E[error]
    end

    S -->|3秒後自動消去| A[Toast表示]
    W -->|5秒後自動消去| A
    E -->|手動クローズのみ| A

    A -->|×ボタン| C[クローズ]
    A -->|Escapeキー| C
    A -->|アクションボタン| C

    style S fill:#d1fae5
    style W fill:#fef3c7
    style E fill:#fee2e2
    style A fill:#e0e7ff
    style C fill:#f3f4f6

• 重大度別の色分け（success/info/warning/error）
• 自動消去タイマー（success/info: 3秒、warning: 5秒、error: 手動のみ）
• 複数Toast同時表示（最大3件）
• アクションボタン付きToast（「再試行」など）
• アクセシビリティ対応（WCAG AA準拠）
• 後方互換性の維持

実装方針

Phase 1-4: 基盤構築

1. src/types/toast.ts - 型定義（ToastSeverity, ToastItem, ShowToastOptions）
2. src/hooks/useToast.ts - カスタムフック（複数Toast管理、タイマー、重複防止）
3. src/components/Toast.tsx - ToastContainerコンポーネント
4. index.css - Tailwind CSSで重大度別スタイル

Phase 5-8: 移行

5. App.tsx - Toast統合、エラー表示移行
6. FileUploadStep - showToast経由のエラー表示
7. StepRenderer - showToast型拡張
8. ResultStep - ダウンロードエラーのToast化

graph TD
    subgraph フロントエンド層
        A[Reactコンポーネント]
        B[Toast.tsx<br/>ToastContainer]
        C[useToastカスタムフック]
    end

    subgraph 状態管理
        D[useState<br/>Toast配列]
        E[useRef<br/>タイマー管理]
        F[useCallback<br/>関数メモ化]
    end

    subgraph 型定義
        G[ToastItem<br/>severity, message]
        H[ShowToastOptions<br/>dedupe, duration]
    end

    A -->|showToast呼び出し| C
    C -->|状態更新| D
    C -->|タイマー設定| E
    D -->|レンダリング| B
    B -->|自動消去| E
    B -->|アクセシビリティ| B

    style A fill:#e0e7ff
    style B fill:#fef3c7
    style C fill:#d1fae5
    style D fill:#fce7f3
    style E fill:#ddd6fe

ポイント

この実装で押さえたポイントを解説します。

1. useRefでタイマー管理（メモリリーク防止）

stateDiagram-v2
    [*] --> Toast作成: showToast呼び出し
    Toast作成 --> タイマー設定: setTimeout実行
    タイマー設定 --> タイマー待機中: timerRefsにIDを保存
    タイマー待機中 --> 自動消去: タイムアウト
    タイマー待機中 --> 手動クローズ: ×ボタン/Escape
    自動消去 --> [*]
    手動クローズ --> [*]

    note right of タイマー待機中
        useRefで管理
        メモリリーク防止
    end note

    note right of 手動クローズ
        clearTimeoutで解除
    end note

useRefでタイマーIDを管理し、コンポーネントのアンマウント時に確実にクリーンアップすることで、メモリリークを防ぎます。

const timerRefs = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());

// クリーンアップ
useEffect(() => {
  return () => {
    timerRefs.current.forEach((timer) => clearTimeout(timer));
    timerRefs.current.clear();
  };
}, []);

2. 重複Toast防止オプション

flowchart TD
    A[showToast呼び出し] --> B{dedupeオプション}
    B -->|false| D[新規Toastを追加]
    B -->|true| C{同一メッセージが<br/>存在する?}

    C -->|はい| E[スキップ<br/>既存Toastを維持]
    C -->|いいえ| F{最大3件に達した?}

    F -->|はい| G[最古のToastを削除]
    F -->|いいえ| D
    G --> D

    D --> H[Toast配列を更新]

    style E fill:#fef3c7
    style H fill:#d1fae5

重複するメッセージのToastを防ぐことで、ユーザー体験を向上させます。

const showToast = useCallback((message: string, options: ShowToastOptions = {}) => {
  if (options.dedupe) {
    const key = options.dedupeKey ?? message;
    const exists = prev.some((t) => t.message === key);
    if (exists) return prev;
  }
  return [...prev, newToast].slice(-MAX_TOASTS);
}, []);

3. アクセシビリティ対応

sequenceDiagram
    participant U as ユーザー
    participant T as Toast
    participant SR as スクリーンリーダー

    Note over T,SR: errorの場合（aria-live="assertive"）
    U->>T: エラーが発生
    T->>SR: role="alert"<br/>aria-live="assertive"
    SR->>U: 🔊 即座に読み上げ<br/>「エラー：ファイルのアップロードに失敗しました」

    Note over T,SR: infoの場合（aria-live="polite"）
    U->>T: 通知が表示
    T->>SR: role="alert"<br/>aria-live="polite"
    SR->>U: 🔊 適宜読み上げ<br/>「保存が完了しました」

    Note over U,T: キーボード操作
    U->>T: Escapeキー押下
    T->>T: onCloseハンドラー実行
    T->>U: Toastが閉じる

WCAG AA準拠のアクセシビリティ対応を実装します。

graph LR
    subgraph old_api["旧API 引き続き動作"]
        A1[toast.showToast<br/>メッセージ]
        A2[toast.closeToast<br/>引数なし]
    end

    subgraph new_api["新API 拡張機能"]
        B1[toast.showToast<br/>エラー<br/>オプション指定]
        B2[個別クローズ<br/>onCloseハンドラー]
    end

    A1 -->|後方互換| B1
    A2 -->|後方互換| B2

    style A1 fill:#e5e7eb
    style A2 fill:#e5e7eb
    style B1 fill:#d1fae5
    style B2 fill:#d1fae5

// 新API
toast.showToast('エラー', { severity: 'error', dedupe: true });

// 旧API（引き続き動作）
toast.showToast('メッセージ');
toast.closeToast(); // 引数なしで全クリア