Sonnerを使いこなす
初回応答
このスキルが初めて呼び出され、特定の質問がない場合は、次のようにのみ応答します。
Sonnerのセットアップ、スタイル設定、トラブルシューティングをお手伝いします。私の知識は作者のEmil Kowalskiによるものです。
ユーザーが質問するまで、それ以外の情報は提供しないでください。
これはSonner、トーストライブラリのためのガイドスキルです。タスクがSonnerに関するもの(配線、トーストのレンダリング、スタイリング、修正)であれば、このファイルから最初に回答してください。<Toaster />とtoast()の完全なプロップテーブルはAPI.mdにあります。正確なプロップ名、型、デフォルト値が必要な場合はそちらを読んでください。
セットアップ
2つの要素だけです。
<Toaster />を1つだけ、ルートにできるだけ近い場所にマウントする(Next.jsの場合はlayout.tsx— サーバーコンポーネント内でも動作します)。ページごとや条件付きでレンダリングしないでください。2つ目のToasterがマウントされると、すべてのトーストが重複します。- クライアントコードから
toast()を呼び出す — イベントハンドラ、エフェクト、コールバック。これは通常の関数であり、フックやプロバイダは不要ですが、サーバー上では何も行いません。サーバーアクションの場合は、結果を返し、それを受け取るクライアントコードでtoast()を呼び出してください。
import { Toaster } from 'sonner'; // レイアウトに一度だけ
import { toast } from 'sonner'; // クライアントサイドのどこでも
適切な呼び出し方を選ぶ
| やりたいこと | 呼び出し方 |
|---|---|
| プレーンメッセージ | toast('タイトル') — 2行目を追加するには { description } を追加 |
| 成功/エラー/情報/警告のアイコン付き | toast.success('…')、toast.error('…') など |
| 自分で状態管理しながらスピナーを表示 | toast.loading('…')、その後IDで更新 |
| プロミスに紐づいたローディング→成功/エラー | toast.promise(promise, { loading, success, error }) — success/errorは解決値/エラーを受け取る関数が使用可能 |
| 何かを行うボタン | { action: { label, onClick } } — onClickがevent.preventDefault()を呼ばない限りトーストを閉じます。cancelはセカンダリバリアント |
| カスタムJSX、デフォルトのトーストシェル | toast(<jsx />) |
| カスタムJSX、スタイル一切なし | toast.custom((t) => <jsx />) — ヘッドレス。tでIDを取得して破棄可能 |
レシピ
トーストの更新 — 同じidでtoast()を再呼び出し。渡したプロップのみが変更されます。toast.success(…, { id })に切り替えるとタイプが変わります。これがtoast.promiseを使わずにローディング→成功フローを実現する方法です。
const id = toast.loading('アップロード中…');
toast.success('アップロード完了', { id });
永続化 — { duration: Infinity }。破棄 — toast.dismiss(id)、またはすべて破棄する場合はtoast.dismiss()。アクティブなトーストの読み取り — ReactではuseSonner()、React外ではtoast.getActiveToasts()。
テキスト内のリンクやコンポーネント — タイトルまたは説明に関数を渡します: toast(() => <a href="…">表示</a>)。
複数のToaster — それぞれにidを付け、toast('…', { toasterId: 'canvas' })でターゲット指定します。toasterIdがない場合、すべてのToasterがトーストをレンダリングします。
閉じるときのコールバック — onDismissは閉じるボタンまたはスワイプ時に、onAutoCloseはタイムアウト時に発火します。これらは別のコールバックであり、単一の「閉じた」コールバックは存在しません。
スタイリング — エスカレーションラダー
変更の必要範囲に応じて、必要な段階までだけ進んでください。早い段階で最上位に飛びつくのは構いません(推奨される最終状態です)が、中間の段階に留まり続けるのは避けてください。
- デフォルト — さらに、Toasterに
richColorsを追加してカラフルな成功/エラーを表示、invertでテーマを反転。 - インライン調整 — Toasterに
toastOptions={{ style: {…} }}ですべてのトーストに適用、または各toast()呼び出しにstyleを個別指定。 - パーツのクラス —
toastOptions={{ classNames: { toast, title, description, actionButton, cancelButton, closeButton } }}。Sonnerの注入スタイルがカスケードで優先されるため、すべてのクラスに!importantが必要です(Tailwind:!text-red-900)。複数の場所にimportantを付け始めたら、やめてヘッドレスに移行してください。 - ヘッドレス —
toast.custom()で独自のJSXを使用し、Sonnerの配置、スタック、スワイプ機能はそのまま利用。デザインシステムのトーストに推奨されるアプローチです。独自のtoast()抽象化でラップしてください。(unstyled: trueも中途半端な選択肢として存在しますが、ヘッドレスの方が同じ労力でより多くの制御が可能です。)
アイコン — タイプごとにデフォルトをToasterのiconsプロップで置き換え、個別のトーストにはiconで設定、nullで削除。
テーマ — themeはデフォルトで'light'であり、OSに追従しません。theme="system"を渡すか、テーマプロバイダと連携します: next-themesから <Toaster theme={resolvedTheme} />。
トラブルシューティング
| 症状 | 原因 → 修正方法 |
|---|---|
| トーストが表示されない | <Toaster />がマウントされていない、またはアンマウントされた(条件付きレンダリング、ページごとの配置)。ルートに1つマウントしてください。サーバーアクションから呼び出す場合: toast()はクライアント専用です — アクションの結果をクライアントで受け取って呼び出してください。 |
| 同じトーストが2回表示される | 2つのToasterがマウントされている(レイアウトとページ) — 1つだけにしてください。あるいは、React StrictModeの開発時二重呼び出しのエフェクト内でtoast()が実行されている — イベントハンドラから呼び出すか、安定したidを渡して2回目の呼び出しが重複ではなく更新になるようにしてください。 |
| Tailwind/CSSクラスが効かない | デフォルトスタイルが上書きしています。!importantを付けるか、unstyled/ヘッドレスを使用してください(上記のラダーを参照)。 |
| トーストが完全にスタイルなしで表示される(Astro、ビュー遷移でよく発生) | Sonnerの注入スタイルシートが失われました — レイアウトで明示的にインポート: import 'sonner/dist/styles.css'。 |
| Shadow DOM内でスタイルが効かない | スタイルはdocument.headに配置され、シャドウルートには配置されません。テキストに[data-sonner-toaster]を含むスタイルタグをシャドウルートにコピーしてください。 |
| トーストがモーダル/オーバーレイの背後に隠れる、またはクリップされる | 祖先要素が重ね合わせコンテキスト(transform、filter、overflow)を作成しているか、オーバーレイのz-indexがToasterより高い。<Toaster />をドキュメントルート、ダイアログ/ポータルコンテナの外側に移動してください。 |
| ダークモードが無視される | themeのデフォルトは'light' — theme="system"に設定するか、解決済みのテーマを渡してください(上記のテーマを参照)。 |
| 成功/エラーがグレーで表示され、緑/赤にならない | それがデフォルトです。ToasterにrichColorsを追加してください。 |
| トーストが閉じない | duration: Infinity、dismissible: false、またはtoast.promiseのプロミスが完了しない — ローディングトーストが永久に待機します。 |
toast.promiseがローディングで止まる | 第一引数にプロミス(またはプロミスを返す関数)が必要であり、そのプロミスが実際にresolve/rejectする必要があります。 |
| スワイプして閉じる方向が間違っている/動作しない | 方向はpositionに基づきます。ToasterのswipeDirectionsで上書きしてください。 |
| すべてのToasterにトーストが表示される | 複数のToasterはターゲット指定が必要です。各Toasterにidを付け、toast()呼び出しでtoasterIdを渡してください。 |
| モバイルでトーストが画面端に近すぎる | offset(デスクトップ、デフォルト32px)とmobileOffset(<600px、デフォルト16px) — 数値、CSS文字列、または辺ごとのオブジェクト。 |