Toast
ユーザーの操作を妨げることなく、「保存しました」などの短いメッセージを一時的に表示します。
Toastに対応するWAI-ARIA APGパターンはありません。トーストはライブリージョンを通じて読み上げられ、キーボードのホットキーで到達可能なランドマーク内に配置され、ユーザーが読んでいる間は表示されたままになります。
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Toast } from '@leve-ui/toast';
import { LuX } from '@qwikest/icons/lucide';
import styles from './default.css?inline';
const MESSAGES = [
{ title: 'Saved', description: 'Your changes were saved.' },
{ title: 'Copied', description: 'The link was copied to the clipboard.' },
{ title: 'Invitation sent', description: 'We emailed the invitation to your teammate.' },
];
// Any component inside the Provider can add toasts
const ShowButton = component$(() => {
const toaster = Toast.useToaster();
const count = useSignal(0);
return (
<button
type="button"
class="toast-default-button"
onClick$={() => {
toaster.add$(MESSAGES[count.value % MESSAGES.length]);
count.value += 1;
}}
>
Show toast
</button>
);
});
// Renders the toasts; put it once, usually at the app root
const Toaster = component$(() => {
const toaster = Toast.useToaster();
return (
<Toast.Region class="toast-default-region">
<Toast.List class="toast-default-list">
{toaster.toasts.value.map((toast) => (
<Toast.Root key={toast.id} toast={toast} class="toast-default-toast">
<Toast.Title class="toast-default-title">{toast.title}</Toast.Title>
<Toast.Description class="toast-default-description">
{toast.description}
</Toast.Description>
<Toast.Close aria-label="Close" class="toast-default-close">
<LuX aria-hidden="true" class="toast-default-icon" />
</Toast.Close>
</Toast.Root>
))}
</Toast.List>
</Toast.Region>
);
});
export default component$(() => {
useStyles$(styles);
return (
<Toast.Provider>
<ShowButton />
<Toaster />
</Toast.Provider>
);
});.toast-default-button {
padding: 8px 12px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.toast-default-button:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.toast-default-button:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* The Region sits at the bottom-end corner of the viewport (data-placement="bottom-end") */
.toast-default-region {
position: fixed;
right: 16px;
bottom: 16px;
z-index: 50;
width: min(356px, calc(100vw - 32px));
font-family: inherit;
}
.toast-default-region:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-default-list {
position: relative;
margin: 0;
padding: 0;
list-style: none;
}
/*
* The toasts are stacked like cards: index 0 is the newest, in front.
* While the pointer is over the Region or focus is in it (data-expanded), they spread out.
*/
.toast-default-toast {
--toast-y: calc(var(--leve-toast-index) * -12px);
--toast-scale: calc(1 - var(--leve-toast-index) * 0.05);
position: absolute;
right: 0;
bottom: 0;
z-index: calc(100 - var(--leve-toast-index));
display: grid;
grid-template-columns: 1fr auto;
gap: 2px 12px;
box-sizing: border-box;
width: 100%;
padding: 14px 16px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
box-shadow: 0 8px 24px rgb(15 23 42 / 0.18);
transform-origin: bottom center;
transform: translateX(var(--leve-toast-swipe-move-x, 0px)) translateY(var(--toast-y))
scale(var(--toast-scale));
/* Show the three newest toasts of the stack */
opacity: clamp(0, 3 - var(--leve-toast-index), 1);
transition:
transform 400ms ease,
opacity 400ms ease;
animation: toast-default-in 400ms ease;
/* Horizontal moves go to the swipe; vertical ones still scroll the page */
touch-action: pan-y;
user-select: none;
}
/* Keeps the pointer over the Region in the gap between expanded toasts */
.toast-default-toast::after {
content: "";
position: absolute;
top: 100%;
right: 0;
left: 0;
height: 12px;
}
/* Behind the front toast, every toast is as tall as the front one */
.toast-default-toast:not([data-front]):not([data-expanded]) {
height: var(--leve-toast-front-height);
overflow: hidden;
}
.toast-default-toast[data-expanded] {
--toast-y: calc(-1 * var(--leve-toast-front-offset) - var(--leve-toast-index) * 12px);
--toast-scale: 1;
opacity: 1;
}
.toast-default-toast:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-default-toast[data-swipe="move"] {
transition: none;
}
/* Closing: fade out; after a swipe, also slide out the rest of the way */
.toast-default-toast[data-state="closed"] {
opacity: 0;
transition:
transform 200ms ease,
opacity 200ms ease;
}
.toast-default-toast[data-swipe="end"] {
transform: translateX(calc(var(--leve-toast-swipe-end-x) + 100%)) translateY(var(--toast-y));
}
@keyframes toast-default-in {
from {
opacity: 0;
transform: translateY(100%);
}
}
.toast-default-title {
font-size: 14px;
font-weight: 600;
}
.toast-default-description {
grid-column: 1;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}
.toast-default-close {
grid-row: 1 / span 2;
grid-column: 2;
align-self: start;
display: inline-flex;
padding: 4px;
border: 0;
border-radius: 4px;
background: transparent;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.toast-default-close:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.toast-default-close:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-default-icon {
width: 16px;
height: 16px;
}
@media (prefers-reduced-motion: reduce) {
.toast-default-toast {
transition: none;
animation: none;
}
}インストール#
個別のパッケージをインストールするか、@leve-ui/coreを使用してすべてのコンポーネントを一度に取得します。
pnpm add @leve-ui/toastnpm install @leve-ui/toastyarn add @leve-ui/toastbun add @leve-ui/toastpnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/core構造#
import { Toast } from '@leve-ui/toast'; // or '@leve-ui/core'
<Toast.Provider>
{/* Your app: call Toast.useToaster().add$() anywhere inside */}
<Toast.Region>
<Toast.List>
{toaster.toasts.value.map((toast) => (
<Toast.Root key={toast.id} toast={toast}>
<Toast.Title />
<Toast.Description />
<Toast.Action />
<Toast.Close />
</Toast.Root>
))}
</Toast.List>
</Toast.Region>
</Toast.Provider>
| パーツ | 要素 | 説明 |
|---|---|---|
Toast.Provider | なし | トーストと設定を保持します。アプリをこれでラップしてください。 |
Toast.Region | <section> | トーストを保持するランドマークです。ホットキーによってフォーカスがここに移動します。 |
Toast.List | <ol> | トーストのリストです。 |
Toast.Root | <li> | 個々のトーストです。useToaster().toastsからトーストを受け取ります。 |
Toast.Title | <div> | タイトルです。 |
Toast.Description | <div> | 省略可能。詳細です。 |
Toast.Action | <button> | 省略可能。「元に戻す」などのアクションです。onClick$の実行後にトーストを閉じます。 |
Toast.Close | <button> | トーストを閉じます。 |
トーストの追加#
Toast.useToaster()はトーストとそれらを変更する関数を返します。Provider内の任意のコンポーネントで呼び出してください。
const toaster = Toast.useToaster();
const id = await toaster.add$({ title: 'Uploading', duration: Infinity });
await toaster.update$(id, { title: 'Uploaded', duration: 3000 });
await toaster.dismiss$(id); // or dismiss$() to close all
| オプション | 説明 |
|---|---|
title / description | テキストです。読み上げにも使用されます。 |
type | ユーザー操作の結果で、すぐに読み上げられる'foreground'(デフォルト)。バックグラウンドタスク用で、現在の読み上げの後に読み上げられる'background'。 |
duration | トーストが表示され続ける時間(ミリ秒単位)。Infinityを指定すると閉じられるまで維持されます。デフォルトはProviderのdurationです。 |
data | レンダリング用独自のデータで、useToaster<T>()で型付けされます。シリアライズ可能である必要があります。 |
トーストはモジュール変数ではなくProviderのコンテキスト内のシグナルで保持されます。サーバー上の各リクエストが独自のトーストを持ち、サーバーで追加されたトーストがクライアントに表示されます。
スタック#
各トーストは、カードのように重ねて表示し、ポインターがRegion上にあるかフォーカスがある間(data-expanded)に展開するためのCSS変数を出力します。上のデモはその一例を示しています:
.toast {
position: absolute;
bottom: 0;
transform: translateY(calc(var(--leve-toast-index) * -12px))
scale(calc(1 - var(--leve-toast-index) * 0.05));
}
.toast[data-expanded] {
transform: translateY(calc(-1 * var(--leve-toast-front-offset) - var(--leve-toast-index) * 12px));
}
例#
アクション#
Toast.Actionを持つトーストは閉じられるまで表示されたままになるため、ユーザーが到達する時間を確保できます。トーストはやがて消えるため、同じアクションをページ内の別の場所にも用意してください。
- report.pdf
- photo.png
- notes.txt
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Toast } from '@leve-ui/toast';
import { LuX } from '@qwikest/icons/lucide';
import styles from './action.css?inline';
// The data your toasts carry, typed through useToaster<T>()
type FileToast = { file: string };
export default component$(() => {
useStyles$(styles);
return (
<Toast.Provider>
<Files />
</Toast.Provider>
);
});
const Files = component$(() => {
const toaster = Toast.useToaster<FileToast>();
const files = useSignal(['report.pdf', 'photo.png', 'notes.txt']);
return (
<div class="toast-action">
<ul class="toast-action-files">
{files.value.map((file) => (
<li key={file} class="toast-action-file">
{file}
<button
type="button"
class="toast-action-button"
onClick$={() => {
files.value = files.value.filter((item) => item !== file);
toaster.add$({ title: 'File deleted', description: file, data: { file } });
}}
>
Delete
</button>
</li>
))}
</ul>
{files.value.length === 0 && <p class="toast-action-empty">No files</p>}
<Toast.Region class="toast-action-region">
<Toast.List class="toast-action-list">
{toaster.toasts.value.map((toast) => (
<Toast.Root key={toast.id} toast={toast} class="toast-action-toast">
<Toast.Title class="toast-action-title">{toast.title}</Toast.Title>
<Toast.Description class="toast-action-description">
{toast.description}
</Toast.Description>
{/* A toast with an Action stays until it is closed */}
<Toast.Action
class="toast-action-undo"
onClick$={() => {
if (toast.data) files.value = [...files.value, toast.data.file];
}}
>
Undo
</Toast.Action>
<Toast.Close aria-label="Close" class="toast-action-close">
<LuX aria-hidden="true" class="toast-action-icon" />
</Toast.Close>
</Toast.Root>
))}
</Toast.List>
</Toast.Region>
</div>
);
});.toast-action {
display: flex;
flex-direction: column;
gap: 8px;
width: 280px;
font-family: inherit;
}
.toast-action-files {
display: flex;
flex-direction: column;
gap: 8px;
margin: 0;
padding: 0;
list-style: none;
}
.toast-action-file {
display: flex;
align-items: center;
justify-content: space-between;
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
}
.toast-action-empty {
margin: 0;
font-size: 14px;
color: light-dark(#475569, #c9ddf0);
}
.toast-action-button {
padding: 4px 10px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
font: inherit;
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
cursor: pointer;
}
.toast-action-button:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.toast-action-button:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* The Region sits at the bottom-end corner of the viewport (data-placement="bottom-end") */
.toast-action-region {
position: fixed;
right: 16px;
bottom: 16px;
z-index: 50;
width: min(356px, calc(100vw - 32px));
font-family: inherit;
}
.toast-action-region:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-action-list {
position: relative;
margin: 0;
padding: 0;
list-style: none;
}
/*
* The toasts are stacked like cards: index 0 is the newest, in front.
* While the pointer is over the Region or focus is in it (data-expanded), they spread out.
*/
.toast-action-toast {
--toast-y: calc(var(--leve-toast-index) * -12px);
--toast-scale: calc(1 - var(--leve-toast-index) * 0.05);
position: absolute;
right: 0;
bottom: 0;
z-index: calc(100 - var(--leve-toast-index));
display: grid;
grid-template-columns: 1fr auto auto;
gap: 2px 12px;
box-sizing: border-box;
width: 100%;
padding: 14px 16px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
box-shadow: 0 8px 24px rgb(15 23 42 / 0.18);
transform-origin: bottom center;
transform: translateX(var(--leve-toast-swipe-move-x, 0px)) translateY(var(--toast-y))
scale(var(--toast-scale));
/* Show the three newest toasts of the stack */
opacity: clamp(0, 3 - var(--leve-toast-index), 1);
transition:
transform 400ms ease,
opacity 400ms ease;
animation: toast-action-in 400ms ease;
/* Horizontal moves go to the swipe; vertical ones still scroll the page */
touch-action: pan-y;
user-select: none;
}
/* Keeps the pointer over the Region in the gap between expanded toasts */
.toast-action-toast::after {
content: "";
position: absolute;
top: 100%;
right: 0;
left: 0;
height: 12px;
}
/* Behind the front toast, every toast is as tall as the front one */
.toast-action-toast:not([data-front]):not([data-expanded]) {
height: var(--leve-toast-front-height);
overflow: hidden;
}
.toast-action-toast[data-expanded] {
--toast-y: calc(-1 * var(--leve-toast-front-offset) - var(--leve-toast-index) * 12px);
--toast-scale: 1;
opacity: 1;
}
.toast-action-toast:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-action-toast[data-swipe="move"] {
transition: none;
}
/* Closing: fade out; after a swipe, also slide out the rest of the way */
.toast-action-toast[data-state="closed"] {
opacity: 0;
transition:
transform 200ms ease,
opacity 200ms ease;
}
.toast-action-toast[data-swipe="end"] {
transform: translateX(calc(var(--leve-toast-swipe-end-x) + 100%)) translateY(var(--toast-y));
}
@keyframes toast-action-in {
from {
opacity: 0;
transform: translateY(100%);
}
}
.toast-action-title {
font-size: 14px;
font-weight: 600;
}
.toast-action-description {
grid-column: 1;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}
.toast-action-undo {
grid-row: 1 / span 2;
grid-column: 2;
align-self: center;
padding: 6px 10px;
border: 0;
border-radius: 6px;
background: #009dfd;
font: inherit;
font-size: 13px;
font-weight: 500;
color: #ffffff;
cursor: pointer;
}
.toast-action-undo:hover {
background: #006ce9;
}
.toast-action-undo:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-action-close {
grid-row: 1 / span 2;
grid-column: 3;
align-self: start;
display: inline-flex;
padding: 4px;
border: 0;
border-radius: 4px;
background: transparent;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.toast-action-close:hover {
background: light-dark(#f1f5f9, #ffffff14);
}
.toast-action-close:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toast-action-icon {
width: 16px;
height: 16px;
}
@media (prefers-reduced-motion: reduce) {
.toast-action-toast {
transition: none;
animation: none;
}
}APIリファレンス#
Provider#
| Prop | デフォルト | 型 |
|---|---|---|
| duration | 5000 | number トーストが表示され続ける時間(ミリ秒単位)。Actionを持つトーストは、閉じられるまで表示され続けます。 |
| placement | 'bottom-end' | 'top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end' Regionを配置する位置。Regionおよびトーストに |
| swipeDirection | – | 'up' | 'down' | 'left' | 'right' トーストをスワイプして閉じる方向。デフォルトは配置位置の最も近い端です。 |
| swipeThreshold | 50 | number トーストを閉じるために必要なスワイプ距離(ピクセル単位)。 |
| hotkey | ['F8'] | string[] Regionにフォーカスを移動するキー。 |
Region#
| Prop | デフォルト | 型 |
|---|---|---|
| label | 'Notifications ({hotkey})' | string リージョンの名前。 |
すべての<section>属性も受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-toast-region | 常に存在 |
data-placement | Providerのplacement |
data-expanded | ポインターがRegion上にあるか、Region内にフォーカスがある場合に存在 |
ライブラリはRegionを配置しません。data-placementまたは独自のクラスを使用して配置してください。
List#
独自のpropはありません。 すべての<ol>属性を受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-toast-list | 常に存在 |
data-placement | Providerのplacement |
data-expanded | ポインターがRegion上にあるか、Region内にフォーカスがある場合に存在 |
Root#
| Prop | デフォルト | 型 |
|---|---|---|
| toast (必須) | – | ToastData
|
すべての<li>属性も受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-toast | 常に存在 |
data-state | "open" | "closed" |
data-type | "foreground" | "background" |
data-placement | Providerのplacement |
data-front | 最新の開いているトーストに存在 |
data-expanded | ポインターがRegion上にあるか、Region内にフォーカスがある場合に存在 |
data-swipe | スワイプ中またはスワイプ後の"move" | "cancel" | "end" |
data-swipe-direction | "up" | "down" | "left" | "right" |
| CSS変数 | 値 |
|---|---|
--leve-toast-index | 前面からの位置:0が最新の開いているトースト |
--leve-toast-count | 開いているトーストの数 |
--leve-toast-front-offset | スタックを展開するための、より新しいトーストの合計の高さ |
--leve-toast-height | このトーストの高さ |
--leve-toast-front-height | 最前面のトーストの高さ(例:背面のトーストの高さを揃えるため) |
--leve-toast-swipe-move-x / -y | data-swipe="move"時の、ここまでのスワイプ移動距離 |
--leve-toast-swipe-end-x / -y | data-swipe="end"時の、スワイプ移動距離 |
閉じられると、トーストはdata-state="closed"を取得し、CSSアニメーションおよびトランジションが完了した後に削除されるため、終了アニメーションを適用できます。
タイトル#
独自のpropはありません。 すべての<div>属性を受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-toast-title | 常に存在 |
説明#
独自のpropはありません。 すべての<div>属性を受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-toast-description | 常に存在 |
アクション#
独自のpropはありません。 すべての<button>属性を受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-toast-action | 常に存在 |
閉じる#
独自のpropはありません。 すべての<button>属性を受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-toast-close | 常に存在 |
アクセシビリティ#
- トーストが追加されると、そのタイトルと説明文は常にページ上に存在するライブリージョンを通じて通知されます。
foregroundにはassertive、backgroundにはpoliteが使用されます。後からページに追加されたライブリージョンは確実に読み上げられない場合があるため、トースト自体はライブリージョンではありません。 Toast.Regionは、「Notifications (F8)」という名前の<section>ランドマークです。labelで名前を変更でき、{hotkey}はホットキーに置き換えられます。- トーストは、ユーザーが操作していない間のみ自動的に閉じます。ポインターがRegion上にある、フォーカスがRegion内にある、ウィンドウがバックグラウンドにある、またはトーストがスワイプされている間はタイマーが一時停止します。Actionを持つトーストは自動的に閉じることはありません。
- アイコンのみを表示する場合は、
Toast.Closeにaria-labelを指定してください。
キーボード操作#
| キー | 説明 |
|---|---|
F8 | フォーカスをRegionに移動します。Providerのhotkeyで変更できます。 |
Tab | トーストおよびそのボタン間を移動します。 |
Escape | トースト上で実行すると、そのトーストを閉じて次のトーストまたはRegionにフォーカスを移動します。 |