Toast | Sodium design system

Kind

When to use it

Use: A job the person started finished while they looked elsewhere: an export, a backfill.
Use: A background event changed: replication fell behind, a worker came back.
Use: An action can be undone for a short time: pause with Undo.
Not for: A problem with the view on screen. Use Alert.
Not for: A field's own error. Use Field.
Not for: A change the person can already see.

6 rules

Must: Mount one Toaster per app, inside the Sodium scope and its SodiumPortalProvider. Because each Toaster is its own live region, and two of them announce every toast twice.
Must: Make a toast's action reachable in the view too, such as Undo in the row's menu. Because the toast leaves on its timer, and a keyboard or screen reader user may never reach its button.
Never: Put a primary Button in a toast. Because a toast reports and never asks, and a slab in the corner takes the page's one primary.
Never: Toast after a change already on screen. Because a toast for what the person can see teaches them to ignore the stack, including the failure that matters.
Must: Use toast.fail for a failure; it holds until closed and is never hidden by the limit. Because a failure that times out unread is a failure nobody saw.
Should: Write a success title in the past tense with its object, under 48 characters.

5 states, highest first

4 checks

: The stack is a live region named Notifications; a fail toast is announced assertively, the rest politely.
: Status is the Status mark and a title that says it; the colour never stands alone.
: F6 moves focus into the stack; the timer and its line stop while focus or the pointer is in it.
: The close is a real button named Dismiss; the action is a real button.

3 keys

6 edge cases

A 120-character title: Wraps; the reading time grows with it, up to 12 seconds.
Five toasts at once: Three show; the newest routine one waits with its timer stopped; a fail always shows.
Phone, 390 wide: The stack spans the width 16px in and clears the home indicator; a swipe down dismisses.
A narrow stack: The action drops under the text, and the X keeps the first line.
Window in the background: The timer and its line pause until it comes back.
Reduced motion: No slide and no timer line; the toast still leaves on time.

7 props

toast(title, options): (ReactNode, ToastOptions) => id
toast.promise(promise, labels): {loading, success, fail}
toast.update(id, kind, title, options): replaces in place
toast.dismiss(id?): (string?) => void
options description, action, id, onClose: ReactNode, {label, onClick}, string, () => void
options timeout: number default reading time
Toaster limit, inline, manager: number, boolean, manager default 3, false

15 tokens