Toast

Non-blocking notifications triggered via a global store.

Dismissible

Show Progress

Placement

Intent

Duration (ms)

5000

Title

Description

toaster.success('Changes saved', { description: 'Your settings have been updated.' });

01 Examples

Toasts fire from the global toaster store, so render <Toaster /> once in your root layout first (its placement picks the screen corner, default bottom-right). Then call toaster.success(title, options) (or .info / .warning / .danger) from anywhere. Without a mounted <Toaster /> nothing appears.

Duration, progress and dismissal

Three settings decide how long a toast lives and how it leaves: duration (0 keeps it up until the reader acts), showProgress, and dismissible={false} for toasts that may only auto-close.

// duration in ms – 0 keeps the toast up until the reader acts
toaster.success('Auto-saved', { duration: 2000 });
toaster.danger('Action required', {
  description: 'Please review the error log.',
  duration: 0
});

// showProgress draws the bar counting the remaining time down
toaster.success('Uploading…', { duration: 6000, showProgress: true });
toaster.success('Uploaded', { duration: 6000, showProgress: false });

// dismissible: false drops the close button – auto-close only
toaster.info('Syncing…', {
  description: 'Please wait.',
  dismissible: false,
  duration: 3000
});

Programmatic Dismiss & Clear

toaster.add() returns a toast ID for targeted dismissal. toaster.clear() removes everything.

const id = toaster.success('Uploading…', { duration: 0 });

// Later…
toaster.dismiss(id);

// Or remove everything
toaster.clear();

Document Editor

Fire the toast from the same handler that does the work, and pass the result into the description.

Document Editor

Start typing your document…

<Button onclick={() => toaster.success('Saved', {
  description: 'Draft saved at ' + new Date().toLocaleTimeString()
})}>Save Draft</Button>

02 Store API

Toaster Store API

All methods on the toaster singleton.

import { toaster } from '@urbicon-ui/blocks';

// Shorthand methods – set intent automatically
toaster.info(title, opts?)      // intent: 'info'
toaster.success(title, opts?)   // intent: 'success'
toaster.warning(title, opts?)   // intent: 'warning'
toaster.danger(title, opts?)    // intent: 'danger'

// Full control via add()
toaster.add({
  intent: 'success',
  title: 'Done',
  description: 'All tasks completed.',
  duration: 5000,        // ms, 0 = persistent
  dismissible: true,     // show close button
  showProgress: true,    // animated progress bar
  action: { label: 'Undo', onClick: (id) => restore(id) },  // primary button
  cancel: { label: 'Dismiss' }                              // secondary/quiet button
}); // → returns toast ID

// Manage toasts
toaster.dismiss(id);  // remove one by ID
toaster.clear();      // remove all

03 Customization

slotClasses Override

Override individual toast slots for a branded look without going fully unstyled.

<Toaster slotClasses={{
  toast: 'border-2 border-violet-500/30 shadow-lg shadow-violet-500/10',
  title: 'text-violet-400 font-bold',
  icon: 'text-violet-400'
}} />

The Toaster is one instance per app, so its slotClasses already act globally. A BlocksProvider preset (presets.Toaster, applied via preset) is mainly useful for sharing a skin between apps or switching skins per surface. See Customization.

04 Accessibility

Live Region

The Toaster container uses aria-live="polite" with aria-relevant="additions removals". Screen readers announce new toasts without interrupting the current task.

Alert Role

Each individual toast is rendered with role="alert", ensuring assistive technologies surface the notification promptly.

Keyboard

Dismiss buttons are focusable via Tab and activate with Enter / Space. The dismiss button has an aria-label="Dismiss".

Non-blocking

Toasts use pointer-events-none on the container so they never block interaction with the underlying page. Only the toasts themselves capture pointer events, so the buttons inside them still work.

Reduced Motion

Fly transitions use the system's duration tokens and are retuned under reduced motion. The countdown progress bar is hidden entirely (a bar that can't animate carries no information). Auto-dismiss timing is unchanged.

05 API Reference

10 props

Prop	Type	Default	Description
`class`	`string`	—	Extra classes merged onto the container element.
`intent` variant	dangerinfoneutralprimary +2 more	`neutral`	Controls the color theme and semantic meaning of the Toast. Affects the overall appearance and user perception. Available options: danger, info, neutral, and 3 more.
`max`	`number`	`5`	Maximum number of toasts visible at once. Oldest are hidden first.
`placement`	`ToastPlacement`	`'bottom-right'`	Screen corner where toasts stack.
`preset`	`string`	—	Apply a named preset registered via `<BlocksProvider presets={{ Toaster: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project.
`slotClasses`	`Partial<Record<ToasterSlots, string>>`	—	Per-slot class overrides merged with (or replacing, when `unstyled`) the default styles.
`transitionDuration`	`number`	—	Override the enter/exit fly animation duration in milliseconds for every toast in this toaster. Defaults to the overlay token `--blocks-overlay-enter-duration` (200ms). Set globally via the CSS custom property or per-instance via this prop. Respects `prefers-reduced-motion`.
`transitionEasing`	`(t: number) => number`	—	Override the enter/exit fly easing. Defaults to the overlay token easing (`quintOut`).
`unstyled`	`boolean`	—	Strip all default tv classes. Use with `slotClasses` for a fully custom look.
`...HTMLAttributes<HTMLDivElement>` inherited	`HTMLAttributes`	—	HTML attributes (excluding: 'children')

06 Types

Store & Type Definitions

Types for the toaster store API. ToastInput defines what you pass to toaster.add(). The shorthand methods accept ToastShorthandOpts.

10 types

Only referenced

Name	Kind	Category	Used by	Description
ToastIntent	type	helper	0	Semantic intent accepted by every toast. Mirrors the design system's standard intent palette.
ToastAction	interface	helper	0	An action or cancel button rendered inside a toast (Sonner-style).
ToastData	interface	helper	0	Internal data shape for a rendered toast. Created by `toaster.add()`.
ToastPromiseOptions	interface	helper	0	Per-state config for `toaster.promise`. Each state is either a plain title string or a full `ToastInput`; `success`/`error` may also be a function of the resolved value / rejection reason.
ToastInput	type	helper	0	Options accepted by `toaster.add()` and the shorthand methods (`info`, `success`, `warning`, `danger`). All fields are optional; sensible defaults are applied internally.
ToastShorthandOpts	type	helper	0	Shorthand options for `toaster.info()`, `toaster.success()`, etc. Title and intent are provided as direct arguments.
ToastProps	interface	props	0	—
ToastVariants	type	variant	0	—
ToasterSlots	type	variant	0	Slot names derived from the tv() config — single source of truth for slotClasses.
ToastPlacement	type	helper	1	—

07 Installation

Import

import { Toaster, toaster } from '@urbicon-ui/blocks';

llm.txt