Toaster
Shows short messages from toast() at the bottom of the window, three at most, each leaving on its own after a few seconds; ButteryProvider mounts one, so an app only calls toast().
import { Toaster } from "@butteryui/react";Demo
toast.success("Deck published")
When to use it
Use it for
- Confirming an action that changed something out of view: Slide deleted, Link copied, Exported
- Offering a quick way back, such as Undo after a delete
- News the person didn't just cause, such as a sync finishing (background: true)
- A result with a tone: toast.success() when it went well, toast.warning() when it needs a look, toast.danger() when it failed
Not for
- Errors in a form: show them next to the field
- Anything people must read or decide on: use a Dialog
- Progress that runs for a while: show a notice with FloatingLanes.Item
- Messages longer than one line: they truncate
- Rendering a Toaster of your own inside ButteryProvider, which already mounts one: call toast(), and pass the Toaster's labels as the provider's toaster to translate them
Examples
Copied toast
A copy button that confirms with one toast, however often it's pressed: the id replaces the last one.
Publish toast
A publish kept in one toast by the id toast() returns, and canceled with toast.dismiss(id); ButteryProvider mounts the Toaster, so there's none to render.
Not published yet
Save result toast
A pretend save that confirms with a success toast, or, with Fail the next save on, explains the failure with a danger one under the same id.
Sync toast
News the person didn't just cause, read out at the next pause: a sync that finishes on its own.
Undo toast
A delete that confirms itself with a toast, with Undo in the toast and on Command or Control Z.
3 slides
Variants and states
Tones
Plain toasts for news; success, warning and danger tint the pill toward their color and lead with an icon. Warnings and dangers stay 5s.
Three at most
Each press adds a toast at the bottom; a fourth lets the oldest go. Hover the toasts and they wait.
One toast per id
A toast that stays until it's replaced: finishing swaps it for one that leaves on its own.
Props
Toaster
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | "Notification" | Read before each message, so screen readers say what it is. Defaults to "Notification". |
regionLabel | string | "Notifications ({hotkey})" | Names the region the toasts stack in. {hotkey} becomes F8, the key that moves focus there.
Defaults to "Notifications ({hotkey})". |
toneLabels | Partial<ToastToneLabels> | The words for each tone, read before its message and naming its icon. Defaults to Success, Warning and Error. |
Also exported
| Export | Description |
|---|---|
toast: ToastFunction | toast(message, options?) shows message in a toast at the bottom of the window and returns the toast's
id: options.id, or one it makes up. Its options: id names the toast, so a later toast with the same
id updates it in place, with its time started over, instead of stacking a copy; action,
{ label, onAction, altText }, adds a button after the message, and altText is another way to do the
same, which screen readers hear; tone is "neutral" (the default), "success", "warning" or
"danger", and toast.success(), toast.warning() and toast.danger() set it, with the tone's icon
and tint; duration is how long it stays, in ms: 3000 by default, 5000 with an action or as a warning
or danger, counted only while the pointer and focus are elsewhere and the window is in front, and
Infinity keeps it until it's dismissed; background: true marks news the person didn't just cause,
which screen readers read at the next pause. Three toasts show at once at most: a fourth lets the one
shown longest ago go. A toast closes when its time is up, when its action is pressed, on Escape or a
swipe down, and with toast.dismiss(id); toast.dismiss() closes them all. F8 moves focus to the
toasts. It shows in the Toaster that ButteryProvider mounts, so inside the provider there's nothing
to render; without the provider, render one <Toaster /> near the root. |
Accessibility
Screen readers hear each toast as it arrives or updates, as "Notification", its tone for a toned toast ("Success:", "Warning:", "Error:"), the message and the action's altText; background toasts wait for a pause. A tone also shows as an icon named by it, so it never rests on color alone. F8 moves focus to the toasts, Tab moves through them newest first, each followed by its action, and Escape closes the focused toast (the newest with the region focused). Escape elsewhere is left alone. When the last toast leaves, focus goes back to where it was. The timer stops while the pointer or focus is on the toasts or the window is in the background. With reduced motion they only fade.
| Keys | What they do |
|---|---|
| F8 | Moves focus to the toasts |
| Tab | Moves through the toasts, newest first, each followed by its action |
| Enter or Space | Runs the focused action, such as Undo, and closes its toast |
| Escape | Closes the focused toast, or the newest while the toasts' region has focus |
Motion
It appears with a `Presence` preset and leaves faster than it came, in about 60% of the time.
With reduced motion: Toasts fade in and out over 100ms without rising, and the stack takes its new place at once.
Layout
Toasts stack in the bottom-center floating lane, 8px apart and three at most, each a pill --bt-h-button (36px) tall and as wide as its message and action, never wider than the lane. A long message truncates with an ellipsis and shows in full as its title, and the action's hit area runs the pill's full height and is at least 24px wide.