Toast

トースト通知

GitHub でソースを見る

プレビュー

トースト通知は画面の端に一時的に表示されるため、ここではプレビューを省略しています。

tone プロパティで通知の種類を指定できます。

使いどころ

使う場面

  • 操作の結果を短く伝える（「保存しました」「リンクをコピーしました」）。数秒で消えても困らない内容
  • tone で重さを選ぶ。default / info / positive は控えめ、warning / negative は強く読み上げられる
  • 表示位置は画面の端で、作業の邪魔をしない。ToastProvider をルートに 1 つ置き、useToast() の toast() で呼ぶ

使わない場面

  • 読み終えるまで残したいメッセージ、取り消せない失敗、次の操作が必要な通知。Alert を使う
  • 確認や選択を求めること。Dialog を使う
  • 入力欄の検証エラー。FormField の error を使う
  • 見逃すと困る内容。自動で消えるので、読めなかった人は取り返せない。ボタンなど操作を載せることもできない

使い方

import type { ReactNode } from "react";
import { Button, ToastProvider, useToast } from "kaze-design-system";

// アプリのルートで 1 回だけ包む
export function Providers({ children }: { children: ReactNode }) {
  return <ToastProvider>{children}</ToastProvider>;
}

// 配下のどのコンポーネントからでも呼べる
export function SaveButton() {
  const { toast } = useToast();
  return (
    <Button
      onClick={() =>
        toast({ title: "保存しました", description: "変更は次回の読み込みから反映されます。", tone: "positive" })
      }
    >
      保存
    </Button>
  );
}

プロパティ

名前型デフォルト説明
children必須ReactNodeなしToastProvider で包むアプリ全体
closeLabelstringなしAccessible label for the close button on each toast (default: "閉じる")
containerLabelstringなしAccessible label for the toast container (default: "通知")
ToastProvidercomponentなしアプリのルートに 1 つ置く。closeLabel / containerLabel で文言を変更可能
useToast(){ toast, dismiss }なしtoast(options) は表示して id を返す。dismiss(id) で閉じる
toast.titlestringなしトーストのタイトル
toast.descriptionstringなし本文（省略可）
toast.tone"default" | "positive" | "negative" | "warning" | "info""default"種類。negative / warning は role=alert で読み上げられる
toast.durationnumber4000自動で閉じるまでのミリ秒。hover / focus 中は止まる

型と必須かどうかはソースの型定義から自動で生成しています。表にない HTML 標準の属性（className や aria-* など）も、ルート要素にそのまま渡せます。

キーボード操作

キー動作
Tab表示中の Toast の閉じるボタンにフォーカスを移す（フォーカス中は自動で閉じるタイマーが止まる）
Enter / Space閉じるボタンを押して Toast を閉じる

アクセシビリティ

  • tone が negative / warning なら role="alert"（即時に割り込んで読み上げ）、それ以外は role="status"（現在の読み上げが終わってから）。緊急でない内容に negative / warning を使わない
  • 自動で閉じるまでの既定は 4000ms。マウスホバーかフォーカスの間はタイマーが止まる（WCAG 2.2.1）。長い文は duration を延ばす
  • Toast は Dialog や Drawer を開いている間も操作でき、背景の inert の対象外
  • closeLabel と containerLabel で閉じるボタンと通知領域の名前を変えられる

文言

  • title は結果を過去形か完了形で短く（「保存しました」「招待を送りました」）
  • 失敗は理由と次の行動を description に書く。ただし重要な失敗は Alert に回す

関連するコンポーネント