ComponentsOverlayToast

Toast

Better than react-toastify · 8 types · 6 positions · promise · progress · rich

DefaultSuccessErrorWarningInfoGradientPromiseProgressRichStackPersistentPositions

Overview

Better than react-toastify · 8 types · 6 positions · promise · progress · rich

Status notifications

Live preview

Trigger each example to see transient feedback without interrupting the current workflow.

ToastExample.tsx
tsx
import { toast } from 'omverse-ui'
 
toast('Default notification')
toast.success('Changes saved!', { description: 'Your profile has been updated' })
toast.error('Failed to save', { description: 'Please check your connection' })
toast.warning('Session expiring', {
description: "You'll be logged out in 5 minutes",
actions: [{ label: 'Extend', onClick: () => toast.success('Session extended!') }],
})
toast.info('New version available', {
description: 'v2.1.0 is ready to install',
actions: [
{ label: 'Update now', onClick: () => toast.loading('Updating...') },
{ label: 'Later', variant: 'ghost', onClick: () => {} },
],
})
toast.gradient('🚀 You reached Pro tier!', {
description: 'Enjoy unlimited projects and priority support',
actions: [{ label: 'View perks', onClick: () => {} }],
})

Use toasts for brief confirmation or status updates that do not require an immediate decision. Keep critical errors close to the affected field or content.

Anatomy

  • Root container and toast wrapper from the Toaster.
  • Primary title and optional secondary description text.
  • Optional avatars, actions, badges, and progress indicators.
  • Dismiss affordance, position stack behavior, and time-based auto-close states.

When to use

  • Use for short, time-scoped system feedback after a user action.
  • Use for transient process updates like saves, uploads, and background tasks.
  • Use when repeated or action-oriented messages are required during interaction.

When not to use

  • Do not use toast for critical legal notices requiring confirmation.
  • Do not rely on toasts alone for irreversible destructive actions.
  • Prefer inline messaging when context is more important than global feedback.

Variants

Variants are driven by helper APIs and styling props such as success, warning, gradient, and custom wrappers.

States

Common states include loading, success, warning, error, info, persistent, dismissed, and promise-based transitions.

Behavior

Toasts queue and stack by default; only the most recent are surfaced when configured with maxToasts.

Accessibility

  • Use explicit, concise wording so users can quickly understand context.
  • Preserve keyboard accessibility for action buttons and close controls.
  • Keep duration and auto-dismiss behavior predictable and consistent.

Content guidelines

  • Keep messages short and action-focused.
  • Use one primary action per toast whenever possible.
  • Match tone to surrounding flows (success, warning, error).

Examples

Types

Live preview

Click any button to fire a toast — Toaster should be mounted in app layout

App.tsx
tsx
import { toast } from 'omverse-ui'
 
toast('Default notification')
toast.success('Changes saved!', { description: 'Your profile has been updated' })
toast.error('Failed to save', { description: 'Please check your connection' })
toast.warning('Session expiring', {
description: "You'll be logged out in 5 minutes",
actions: [{ label: 'Extend', onClick: () => toast.success('Session extended!') }],
})
toast.info('New version available', {
description: 'v2.1.0 is ready to install',
actions: [
{ label: 'Update now', onClick: () => toast.loading('Updating...') },
{ label: 'Later', variant: 'ghost', onClick: () => {} },
],
})
toast.gradient('🚀 You reached Pro tier!', {
description: 'Enjoy unlimited projects and priority support',
actions: [{ label: 'View perks', onClick: () => {} }],
})

Promise toast

Live preview

Shows loading → resolves to success or error automatically

Shows loading while the promise runs, then switches to success or error

App.tsx
tsx
toast.promise(
new Promise((resolve, reject) => {
setTimeout(() => {
Math.random() > 0.3 ? resolve('done') : reject(new Error('Failed'))
}, 2000)
}),
{
loading: 'Saving changes...',
success: 'Changes saved successfully!',
error: (err) => `Error: ${err instanceof Error ? err.message : 'Unknown error'}`,
}
)

Progress toast

Live preview

Progress updates in real time and transitions to success when complete

Starts a progress toast that increments every 400 ms

App.tsx
tsx
// Start a progress toast — returns an ID
const id = toast.progress('Uploading files...', { description: '0% complete' })
 
// Update it as progress changes
let pct = 0
const interval = setInterval(() => {
pct += Math.random() * 15
if (pct >= 100) {
clearInterval(interval)
toast.update(id, {
type: 'success',
title: 'Upload complete!',
description: '8 files uploaded successfully',
duration: 4000,
dismissible: true,
progress: undefined,
})
} else {
toast.update(id, {
description: `${Math.round(pct)}% complete`,
progress: Math.round(pct),
})
}
}, 400)

Rich toast — avatar + actions

Live preview

Collaborative and social notifications with avatars and action buttons

App.tsx
tsx
toast.rich({
type: 'info',
title: 'John invited you to a project',
description: 'Design System v2.0 · 5 members',
avatarSrc: 'https://i.pravatar.cc/150?img=1',
avatarName: 'John Doe',
actions: [
{ label: 'Accept', onClick: () => toast.success('Joined project!') },
{ label: 'Decline', variant: 'ghost', onClick: () => {} },
],
duration: 8000,
})

Persistent + dismiss

Live preview

Use a stable id to update or dismiss a specific toast at any time

App.tsx
tsx
// Show a persistent loading toast with a stable ID
toast.loading('Connecting to server...', { id: 'persistent' })
 
// Dismiss it later by ID
toast.dismiss('persistent')
 
// Dismiss every visible toast
toast.dismissAll()

Stack — hover to expand

Live preview

Multiple toasts stack and can be viewed in one interaction

Toasts stack with a collapsed view and expand on hover.

App.tsx
tsx
toast.success('Profile updated successfully')
setTimeout(() => toast.error('Payment failed', { description: 'Card declined' }), 100)
setTimeout(() => toast.info('New message from Alice'), 200)
// Multiple toasts stack — hover over them to expand

Position

Live preview

Set position on the Toaster component in your app root

Toast position is controlled by the Toaster component. Place it once in your app root with your preferred position.

top-lefttop-centertop-rightbottom-leftbottom-centerbottom-right
layout.tsx
tsx
// Place <Toaster> once at your app root and set position there
import { Toaster } from 'omverse-ui'
 
export default function RootLayout({ children }) {
return (
<>
{children}
<Toaster position="bottom-right" />
</>
)
}

Props / API

Toast props

Props

PropTypeDefaultDescription
titlestring—Toast message — first argument to toast()
descriptionstringundefinedSecondary line of text below the title
durationnumber4000Auto-dismiss delay in ms. Pass Infinity to persist until dismissed
actionsToastAction[]undefinedAction buttons rendered inside the toast
avatarSrcstringundefinedAvatar image URL — shown in rich toasts
avatarNamestringundefinedAvatar fallback name — used for initials
progressnumberundefined0–100 progress value for toast.progress() toasts
dismissiblebooleantrueShows a close button on the toast
idstringautoStable ID — reuse to update or dismiss a specific toast

Toaster props

Props

PropTypeDefaultDescription
position'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right''bottom-right'Where the toast stack appears on screen
maxToastsnumber5Maximum number of toasts visible at once before older ones are removed