Skip to content

Toast ​

<ore-toast> is a declarative notification host. It renders the notification store for its scope; application code always creates, updates, and dismisses notifications through a toast service.

Basic Usage ​

Place a host once, then use the singleton service:

Full width

If no host exists, the service creates one in document.body on first use. The host is intentionally render-only: it has no add, update, dismiss, or clear methods.

Statuses ​

Every notification sits on a neutral surface that adapts to light and dark themes. The status option communicates severity: it renders a status icon and tints the accent (the progress bar), while the surface stays neutral so toasts never fight the page beneath them.

Full width
StatusIconDefault urgency
neutralnonepolite
infoinfopolite
successcheckpolite
warningtriangle alertpolite
dangercircle alertassertive

Avatar ​

For person-centric notifications, pass an avatar object (any ore-avatar prop) to fill the leading slot with an avatar instead of the status glyph. The status still tints the accent and sets the screen-reader urgency; only its icon is replaced.

Full width

Heading & Metadata ​

Add a heading and meta (such as a timestamp) to provide structured context.

Full width

Action Buttons ​

Attach interactive action buttons that execute callbacks before dismissing. A single action defaults to a light ghost button; give each action an emphasis when the choice has hierarchy.

Full width

Confirm and cancel ​

Actions carry the same emphasis roles as buttons: primary (accent fill), cancel (neutral ghost), and destructive (error ink). Keep exactly one primary per toast, just like a dialog footer. Action emphasis is deliberately independent of the toast status: a danger toast's Undo is a recovery action, not a destructive one, so coloring actions from the status would read backwards.

Full width

Snackbar ​

Set snackbar: true for small, transient confirmations: a compact bar on an inverted surface (dark chip in light themes, light chip in dark themes) that sizes to its content. With an action it persists until dismissed:

Full width

Positions ​

Set position on <ore-toast> to control list placement (top-left, top-center, top-right, bottom-left, bottom-center, bottom-right).

Full width

Declarative host ​

Use attributes to set a host's placement and notification limit:

html
<ore-toast position="top-right" max="3"></ore-toast>
AttributeDefaultDescription
positionbottom-righttop-* or bottom-* list anchor
max5Maximum live notifications per scope: attribute changes apply live

Toast service ​

The toast singleton owns notification state, timers, lifecycle, and mutations.

ts
import { toast } from '@vielzeug/refine/toast';

const id = toast.add({
  duration: 0,
  dismissible: false,
  message: 'Uploading file…',
});

toast.update(id, {
  duration: 3000,
  dismissible: true,
  message: 'Upload complete!',
  status: 'success',
});

toast.dismiss(id);
toast.clear();

Use the colour shortcuts for common notifications:

ts
toast.success('Profile saved');
toast.info('A new version is available');
toast.warning('Your session expires soon');
toast.error('Upload failed', { duration: 0 });

Notification options ​

ts
toast.add({
  actions: [{ label: 'Undo', onClick: undo }],
  heading: 'Message sent',
  message: 'Your message was delivered.',
  meta: 'Just now',
  status: 'success',
  duration: 5000,
});
OptionDefaultDescription
messageN/ARequired notification text
idgeneratedStable notification identifier
statusneutralneutral, info, success, warning, or danger: renders a status icon, tints the accent, and (for danger) raises urgency
avatarN/Aore-avatar props (initials, src, alt, color, status): fills the leading slot instead of the status icon
headingN/AAlert heading
duration5000; 0 for action toastsAuto-dismiss delay in milliseconds; 0 keeps it visible. Entries carrying actions persist until dismissed by default: keyboard and screen-reader users reach toasts last in tab order, so a timed expiry would expire the choice unseen
dismissibletrueShows the close button
snackbarfalseMaterial-style compact bar: inverted neutral surface, single-row padding, text-style actions
actionsN/AButtons (ghost text buttons by default) that run onClick then dismiss. Each action takes emphasis (primary / cancel / destructive / normal) plus optional color/variant overrides
replacefalseReplace a live entry with the same message instead of stacking a duplicate
urgencyderivedpolite or assertive; danger is assertive by default
onDismissN/ACalled after the exit animation completes

toast.update(id, changes) patches only the provided fields: omitted ones leave the entry (and its timer) unchanged.

Promise helper ​

toast.promise() keeps a persistent loading notification and updates it when the promise settles.

ts
await toast.promise(uploadFile(), {
  loading: 'Uploading…',
  success: (url) => `Uploaded to ${url}`,
  error: (error) => `Upload failed: ${String(error)}`,
});

Scoped services ​

Create a scoped service for notifications inside a drawer, dialog, or application region. The service binds to the declarative host in that root, or lazily creates one there.

ts
import { createToastService } from '@vielzeug/refine/toast';

const drawerToast = createToastService(drawerElement);

drawerToast.configure({ max: 3, position: 'top-center' });
drawerToast.success('Saved inside the drawer');

// Dispose a scoped service when its owning region is permanently removed.
drawerToast.dispose();

Services created with the same root share one store. Different roots are isolated.

configure() applies immediately: position writes the host attribute, and max reaches the store through the host's own max watch. Calling it before the first notification simply configures the host that gets created lazily.

Observing transitions ​

tap() exposes add, dismiss, and dispose transitions as a side channel: for analytics, logging, or syncing notifications to storage. Handler errors are swallowed; observation never affects toast behavior.

ts
import { toast } from '@vielzeug/refine/toast';

const stop = toast.tap((event) => {
  if (event.type === 'add') console.log('shown', event.id);
  if (event.type === 'dismiss') console.log('removed', event.id);
});

stop(); // detach

Behavior and accessibility ​

Notifications render as a vertical list anchored to the host position: newest nearest the anchored edge, so every notification stays readable and reachable with a pointer, touch, or keyboard. Each notification is announced once through the host's polite or assertive live region; the embedded alert itself carries no live-region semantics.

Timed notifications show a thin progress bar along the bottom edge. Hovering or focusing the list pauses auto-dismiss timers and the bar; leaving resumes the remaining duration. Timers also pause while a top-layer surface (an open dialog, fullscreen) covers the toasts: the user cannot interact with them, so choices never expire unseen.

Users can dismiss closable notifications with the close button, a horizontal swipe, or the Escape key. Escape dismisses the notification holding focus; pressed anywhere else it dismisses the newest dismissible notification, unless an open top-layer surface owns the key. When a removed notification held focus, focus returns to the element focused before it, so keyboard users keep their place instead of restarting from the document top.

Swipe dismissal leaves controls and [data-no-swipe] subtrees untouched. A second touch cancels the gesture; vertical scrolling and pinch zoom remain native. Dismissal and exit direction use the same projected motion, so a reversing fling never sends the notification in the opposite direction.

Notifications fade and slide in and out. Entry is pure CSS (@starting-style supplies the pre-mount frame, so no script drives it); exit runs the --toast-exit-duration transition and removes the node the moment that transition ends, so a themed exit duration is honored in full rather than clipped to a fixed timer. A swipe-to-dismiss flight reuses the same exit duration, keeping fade, swipe, and removal in lockstep. When a notification enters or leaves the stack, the neighbours slide to their new slots instead of snapping; the reflow follows the same motion rules. Under Motion Mode reduction (the OS preference or data-motion='reduced') the transitions collapse to instant and the progress bar stays hidden; data-motion='full' opts back in despite an OS reduction. On narrow viewports (≤ 480px) notifications span the full width above the safe-area inset, and horizontal snackbars stack their action below a wrapped message.

Every notification renders on the same opaque neutral surface (--toast-bg) that adapts to light and dark themes; only the status icon and progress bar carry the status colour. Multiple notifications exit independently, and all timers and subscriptions are cleaned up when a scoped service is disposed.

CSS custom properties ​

PropertyDescriptionDefault
--toast-max-widthNotification width cap (full width on phones)400px
--toast-gapGap between notificationsvar(--size-2)
--toast-bgNotification surface (neutral, light-dark adaptive)var(--color-contrast-100)
--toast-colorNotification text colourvar(--color-contrast-800)
--toast-border-colorNotification border8% var(--color-contrast-900)
--toast-icon-sizeStatus icon sizevar(--size-5)
--toast-avatar-sizeLeading avatar diametervar(--size-8)
--toast-snackbar-bgSnackbar surfacevar(--color-contrast-900)
--toast-snackbar-colorSnackbar text colourvar(--color-contrast-100)
--toast-snackbar-paddingSnackbar paddingvar(--size-2) var(--size-4)
--toast-snackbar-heightSnackbar message row height, action or notvar(--size-8)
--toast-snackbar-shadowSnackbar elevation shadowvar(--shadow-lg)
--toast-shadowElevation shadowvar(--shadow-xl)
--toast-enter-duration / --toast-exit-durationMotion durationsvar(--duration-200)
--toast-progress-heightHeight of the auto-dismiss progress bar3px
--toast-progress-colorColour of the auto-dismiss progress barStatus accent colour
--toast-inset-top / --toast-inset-bottom / --toast-inset-left / --toast-inset-rightViewport insetsvar(--size-4)
--toast-z-indexStacking ordervar(--z-toast)

CSS parts ​

PartDescription
containerNotification list
toast-wrapperPer-notification layout wrapper (swipe target)
toast-innerPer-notification motion target
progressAuto-dismiss progress bar