Toast

A toast is a transient message for something that just happened: a save, a failure, an undoable delete. ZUI ships Sonner under its own vocabulary and stylesheet, so a toast reads the same tokens as an Alert and a retheme moves both.

import Toaster, { toast } from '@zuilib/primitives/toast'

sonner is a dependency of @zuilib/primitives; nothing extra to install. The toast surfaces are styled in the package stylesheet, so every entry (styles.css, tailwind.css, zui.css) already carries them.

Mount once

Toaster renders the live region. Put it once at the root of the app, next to your routes, not inside a subtree that unmounts.

export function App() {
  return (
    <>
      <Toaster />
      <Routes />
    </>
  )
}

The toasts pad past env(safe-area-inset-*), so they clear a phone's notch and home indicator.

Fire a toast

toast is Sonner's function, unchanged: toast(), toast.success(), toast.error(), toast.warning(), toast.info(), toast.loading(), toast.promise() and toast.dismiss().

Loading example

toast.promise follows an async call from loading to success or error:

toast.promise(save(), {
  loading: 'Saving…',
  success: 'Saved',
  error: 'Failed to save',
})

Props

ToasterProps extends Sonner's ToasterProps; every Sonner prop passes through. ZUI changes the defaults below.

Prop	Type	Default	Description
theme	'light' | 'dark' | 'system'	'light'
position	Position	'bottom-right'
duration	number	4000	Milliseconds a toast stays
closeButton	boolean	true
richColors	boolean	false	Kept off: the tones come from the tokens, not from Sonner

Types: Toast (Sonner's ToastT) and ToastOptions (Sonner's ExternalToast), both from @zuilib/primitives/toast.

Tokens

Token	Used for
--info, --info-border, --info-foreground	The default toast surface
--success, --success-foreground	toast.success
--danger, --danger-foreground	toast.error
--shadow-3, --radius-lg, --spacing	Elevation, corners and padding
--text-sm, --font-weight-semibold	Title and description type
--duration-fast, --ease-standard	Button hover transitions

Action, cancel and close buttons tint from the toast's own text colour, so they stay readable on every surface. Styling targets Sonner's data attributes ([data-sonner-toast], [data-type="success"], [data-button], [data-cancel], [data-close-button]).

Accessibility

• Sonner renders the toasts in a live region; screen readers announce new toasts without moving focus.
• Keep closeButton on so a toast can be dismissed without waiting.
• Toasts are for transient feedback. A message that must be read stays in the page as an Alert.

Related

• Alert: the persistent, in-page counterpart.
• Form: show toast.error on a failed submit.