Add this component

npx zentauri-ui add toast

Accessibility notes

Overlay patterns include focus, dismissal, and semantic roles where the component owns interaction. Verify trigger labels and escape behavior in your flow.

Dependency notes

Static imports do not pull framer-motion. Use the animated entry only when you want motion and have framer-motion installed.

Feedback

Toasts for transient notifications

Toasts acknowledge background work—saved settings, queued jobs, or soft failures—without modal interruption. Integrate them in React apps and Next.js client islands that own global providers.

Examples

Compact size for lightweight confirmations.

Toast variants playground

Pick an appearance and size to preview the toast trigger live. Toggle Show output / Show code and the hook call updates to match the selected variant.

Appearance

Size

All appearances

Every shipped appearance token at a glance. Click any swatch to load it into the playground above.

default

Sample notification.

success

Sample notification.

warning

Sample notification.

error

Sample notification.

info

Sample notification.

ghost

Sample notification.

purple

Sample notification.

pink

Sample notification.

orange

Sample notification.

yellow

Sample notification.

teal

Sample notification.

indigo

Sample notification.

emerald

Sample notification.

gray

Sample notification.

amber

Sample notification.

violet

Sample notification.

gradient-blue

Sample notification.

gradient-green

Sample notification.

gradient-red

Sample notification.

gradient-yellow

Sample notification.

gradient-purple

Sample notification.

gradient-teal

Sample notification.

gradient-indigo

Sample notification.

gradient-pink

Sample notification.

gradient-orange

Sample notification.

blue

Sample notification.

cyan

Sample notification.

green

Sample notification.

lime

Sample notification.

mint

Sample notification.

ocean

Sample notification.

sapphire

Sample notification.

lavender

Sample notification.

ruby

Sample notification.

red

Sample notification.

slate

Sample notification.

zinc

Sample notification.

stone

Sample notification.

royal

Sample notification.

electric

Sample notification.

forest

Sample notification.

sunset

Sample notification.

magenta

Sample notification.

crimson

Sample notification.

aqua

Sample notification.

plum

Sample notification.

Toast API

Generated from the package prop types and variant definitions.

Toast

ToastProps

Variants

Prop	Type	Default
appearance	`amberaquabluecrimsoncyandefaultelectricemeralderrorforestghostgradient-blue`+34	default
size	`lgmdsm`	md

Behavior

Prop	Type	Default
animation	`ToastAnimation \| undefined`	none
toastId*	`string`	none

Content

Prop	Type	Default
children	`ReactNode`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

ToastProvider

ToastProviderProps

Content

Prop	Type	Default
children	`ReactNode`	none

ToastRootVariant

ToastRootVariantProps

Behavior

Prop	Type	Default
appearance	'default' \| 'ghost' \| 'blue' \| 'cyan' \| 'green' \| 'lime' \| 'mint' \| 'ocean' \| 'sapphire' \| 'lavender' \| 'ruby' \| 'red' \| 'slate' \| 'zinc' \| 'stone' \| 'royal' \| 'electric' \| 'forest' \| 'sunset' \| 'magenta' \| 'crimson' \| 'aqua' \| 'plum' \| 'purple' \| 'pink' \| 'orange' \| 'yellow' \| 'teal' \| 'indigo' \| 'emerald' \| 'gradient-blue' \| 'gradient-green' \| 'gradient-red' \| 'gradient-yellow' \| 'gradient-purple' \| 'gradient-teal' \| 'gradient-indigo' \| 'gradient-pink' \| 'gradient-orange' \| 'success' \| 'warning' \| 'error' \| 'info' \| 'gray' \| 'violet' \| 'amber' \| null \| undefined	none
size	`'md' \| 'sm' \| 'lg' \| null \| undefined`	none

ToastViewport

ToastViewportProps

Variants

Prop	Type	Default
position	`bottom-centerbottom-leftbottom-righttop-centertop-lefttop-right`	bottom-right

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none

ToastViewportVariant

ToastViewportVariantProps

Behavior

Prop	Type	Default
position	`'bottom-right' \| 'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| null \| undefined`	none

CSS variable overrides

Toast CSS variables

Override these toast variables on :root, a theme selector, or a component wrapper.

280 variables

Pattern: --zui-<component>-<slot?>-<variant?>-<property>-<state?>-dark?

:root {
  --zui-toast-root-bg: oklch(98.4% 0.003 247.858);
  --zui-toast-root-fg: oklch(20.8% 0.042 265.755);
  --zui-toast-root-shadow: 0 8px 24px rgba(15,23,42,0.12);
  --zui-toast-root-default-bg: oklch(12.9% 0.042 264.695);
  --zui-toast-root-default-fg: oklch(98.4% 0.003 247.858);
  --zui-toast-root-success-border: oklch(69.6% 0.17 162.48 / 0.4);
  --zui-toast-root-success-bg: oklch(26.2% 0.051 172.552);
  --zui-toast-root-success-fg: oklch(97.9% 0.021 166.113);
  --zui-toast-root-warning-border: oklch(76.9% 0.188 70.08 / 0.4);
  --zui-toast-root-warning-bg: oklch(27.9% 0.077 45.635);
  --zui-toast-root-warning-fg: oklch(98.7% 0.022 95.277);
  --zui-toast-root-error-border: oklch(64.5% 0.246 16.439 / 0.5);
  --zui-toast-root-error-bg: oklch(27.1% 0.105 12.094);
  --zui-toast-root-error-fg: oklch(96.9% 0.015 12.422);
  --zui-toast-root-info-border: oklch(68.5% 0.169 237.323 / 0.4);
  --zui-toast-root-info-bg: oklch(29.3% 0.066 243.157);
  --zui-toast-root-info-fg: oklch(97.7% 0.013 236.62);
  --zui-toast-root-ghost-border: transparent;
  --zui-toast-root-ghost-bg: transparent;
  --zui-toast-root-ghost-fg: oklch(20.8% 0.042 265.755);
  --zui-toast-root-purple-border: oklch(43.8% 0.218 303.724);
  --zui-toast-root-purple-bg: oklch(29.1% 0.149 302.717);
  --zui-toast-root-purple-fg: oklch(97.7% 0.014 308.299);
  --zui-toast-root-pink-border: oklch(45.9% 0.187 3.815);
  --zui-toast-root-pink-bg: oklch(28.4% 0.109 3.907);
  --zui-toast-root-pink-fg: oklch(97.1% 0.014 343.198);
  --zui-toast-root-orange-border: oklch(47% 0.157 37.304);
  --zui-toast-root-orange-bg: oklch(26.6% 0.079 36.259);
  --zui-toast-root-orange-fg: oklch(98% 0.016 73.684);
  --zui-toast-root-yellow-border: oklch(47.6% 0.114 61.907);
  --zui-toast-root-yellow-bg: oklch(28.6% 0.066 53.813);
  --zui-toast-root-yellow-fg: oklch(98.7% 0.026 102.212);
  --zui-toast-root-teal-border: oklch(43.7% 0.078 188.216);
  --zui-toast-root-teal-bg: oklch(27.7% 0.046 192.524);
  --zui-toast-root-teal-fg: oklch(98.4% 0.014 180.72);
  --zui-toast-root-indigo-border: oklch(39.8% 0.195 277.366);
  --zui-toast-root-indigo-bg: oklch(25.7% 0.09 281.288);
  --zui-toast-root-indigo-fg: oklch(96.2% 0.018 272.314);
  --zui-toast-root-emerald-border: oklch(43.2% 0.095 166.913);
  --zui-toast-root-emerald-bg: oklch(26.2% 0.051 172.552);
  --zui-toast-root-emerald-fg: oklch(97.9% 0.021 166.113);
  --zui-toast-root-gray-border: oklch(27.8% 0.033 256.848);
  --zui-toast-root-gray-bg: oklch(13% 0.028 261.692);
  --zui-toast-root-gray-fg: oklch(98.5% 0.002 247.839);
  --zui-toast-root-amber-border: oklch(47.3% 0.137 46.201);
  --zui-toast-root-amber-bg: oklch(27.9% 0.077 45.635);
  --zui-toast-root-amber-fg: oklch(98.7% 0.022 95.277);
  --zui-toast-root-violet-border: oklch(43.2% 0.232 292.759);
  --zui-toast-root-violet-bg: oklch(28.3% 0.141 291.089);
  --zui-toast-root-violet-fg: oklch(96.9% 0.016 293.756);
  --zui-toast-root-gradient-blue-border: oklch(42.4% 0.199 265.638);
  --zui-toast-root-gradient-blue-from: oklch(97% 0.014 254.604);
  --zui-toast-root-gradient-blue-to: oklch(97.7% 0.014 308.299);
  --zui-toast-root-gradient-green-border: oklch(44.8% 0.119 151.328);
  --zui-toast-root-gradient-green-from: oklch(98.2% 0.018 155.826);
  --zui-toast-root-gradient-green-to: oklch(98.6% 0.031 120.757);
  --zui-toast-root-gradient-red-border: oklch(44.4% 0.177 26.899);
  --zui-toast-root-gradient-red-from: oklch(97.1% 0.013 17.38);
  --zui-toast-root-gradient-red-to: oklch(97.1% 0.014 343.198);
  --zui-toast-root-gradient-yellow-border: oklch(47.6% 0.114 61.907);
  --zui-toast-root-gradient-yellow-from: oklch(98.7% 0.026 102.212);
  --zui-toast-root-gradient-yellow-to: oklch(98% 0.016 73.684);
  --zui-toast-root-gradient-purple-border: oklch(43.8% 0.218 303.724);
  --zui-toast-root-gradient-purple-from: oklch(97.7% 0.014 308.299);
  --zui-toast-root-gradient-purple-to: oklch(97.1% 0.014 343.198);
  --zui-toast-root-gradient-teal-border: oklch(43.7% 0.078 188.216);
  --zui-toast-root-gradient-teal-from: oklch(98.4% 0.014 180.72);
  --zui-toast-root-gradient-teal-to: oklch(98.4% 0.019 200.873);
  --zui-toast-root-gradient-indigo-border: oklch(39.8% 0.195 277.366);
  --zui-toast-root-gradient-indigo-from: oklch(96.2% 0.018 272.314);
  --zui-toast-root-gradient-indigo-to: oklch(97.7% 0.014 308.299);
  --zui-toast-root-gradient-pink-border: oklch(45.9% 0.187 3.815);
  --zui-toast-root-gradient-pink-from: oklch(97.1% 0.014 343.198);
  --zui-toast-root-gradient-pink-to: oklch(96.9% 0.015 12.422);
  --zui-toast-root-gradient-orange-border: oklch(47% 0.157 37.304);
  --zui-toast-root-gradient-orange-from: oklch(98% 0.016 73.684);
  --zui-toast-root-gradient-orange-to: oklch(97.1% 0.013 17.38);
  --zui-toast-root-blue-border: #2563eb;
  --zui-toast-root-blue-bg: #2563eb14;
  --zui-toast-root-blue-fg: #0f172a;
  --zui-toast-root-cyan-border: #0891b2;
  --zui-toast-root-cyan-bg: #0891b214;
  --zui-toast-root-cyan-fg: #0f172a;
  --zui-toast-root-green-border: #16a34a;
  --zui-toast-root-green-bg: #16a34a14;
  --zui-toast-root-green-fg: #0f172a;
  --zui-toast-root-lime-border: #65a30d;
  --zui-toast-root-lime-bg: #65a30d14;
  --zui-toast-root-lime-fg: #0f172a;
  --zui-toast-root-mint-border: #10b981;
  --zui-toast-root-mint-bg: #10b98114;
  --zui-toast-root-mint-fg: #0f172a;
  --zui-toast-root-ocean-border: #0284c7;
  --zui-toast-root-ocean-bg: #0284c714;
  --zui-toast-root-ocean-fg: #0f172a;
  --zui-toast-root-sapphire-border: #1d4ed8;
  --zui-toast-root-sapphire-bg: #1d4ed814;
  --zui-toast-root-sapphire-fg: #0f172a;
  --zui-toast-root-lavender-border: #8b5cf6;
  --zui-toast-root-lavender-bg: #8b5cf614;
  --zui-toast-root-lavender-fg: #0f172a;
  --zui-toast-root-ruby-border: #be123c;
  --zui-toast-root-ruby-bg: #be123c14;
  --zui-toast-root-ruby-fg: #0f172a;
  --zui-toast-root-red-border: #dc2626;
  --zui-toast-root-red-bg: #dc262614;
  --zui-toast-root-red-fg: #0f172a;
  --zui-toast-root-slate-border: #475569;
  --zui-toast-root-slate-bg: #47556914;
  --zui-toast-root-slate-fg: #0f172a;
  --zui-toast-root-zinc-border: #52525b;
  --zui-toast-root-zinc-bg: #52525b14;
  --zui-toast-root-zinc-fg: #0f172a;
  --zui-toast-root-stone-border: #57534e;
  --zui-toast-root-stone-bg: #57534e14;
  --zui-toast-root-stone-fg: #0f172a;
  --zui-toast-root-royal-border: #4338ca;
  --zui-toast-root-royal-bg: #4338ca14;
  --zui-toast-root-royal-fg: #0f172a;
  --zui-toast-root-electric-border: #0ea5e9;
  --zui-toast-root-electric-bg: #0ea5e914;
  --zui-toast-root-electric-fg: #0f172a;
  --zui-toast-root-forest-border: #166534;
  --zui-toast-root-forest-bg: #16653414;
  --zui-toast-root-forest-fg: #0f172a;
  --zui-toast-root-sunset-border: #ea580c;
  --zui-toast-root-sunset-bg: #ea580c14;
  --zui-toast-root-sunset-fg: #0f172a;
  --zui-toast-root-magenta-border: #c026d3;
  --zui-toast-root-magenta-bg: #c026d314;
  --zui-toast-root-magenta-fg: #0f172a;
  --zui-toast-root-crimson-border: #b91c1c;
  --zui-toast-root-crimson-bg: #b91c1c14;
  --zui-toast-root-crimson-fg: #0f172a;
  --zui-toast-root-aqua-border: #0f766e;
  --zui-toast-root-aqua-bg: #0f766e14;
  --zui-toast-root-aqua-fg: #0f172a;
  --zui-toast-root-plum-border: #7e22ce;
  --zui-toast-root-plum-bg: #7e22ce14;
  --zui-toast-root-plum-fg: #0f172a;
}

/* Dark theme variables follow the same names with -dark appended. */
.dark {
  --zui-toast-root-bg-dark: oklch(98.4% 0.003 247.858);
  --zui-toast-root-fg-dark: oklch(98.4% 0.003 247.858);
}

What it does

Limit concurrent toasts and preserve reading order for screen readers.

Provide action buttons sparingly to reduce accidental clicks.

Composition and API

Prefer compound subcomponents instead of one oversized prop bag. Export a small, documented API for your design system.

Never rely solely on toasts for critical legal consent.

Common use cases

Confirm CRUD actions after server mutations.
Surface copy-to-clipboard success.
Notify when async exports finish.
Warn about connectivity retries.

Accessibility

Keyboard order, focus rings, and ARIA attributes should match production usage. Test with your supported browsers and assistive technologies when semantics are non-trivial.

This preview page exposes a single h1 in the hero for a clean outline.

Next.js integration notes

Colocate examples under the App Router, keep server and client boundaries explicit, and avoid pulling interactive overlays into unexpected server layouts.

Set NEXT_PUBLIC_SITE_URL so canonical and Open Graph URLs resolve on deploy.

FAQ

Does the Toast component work with Next.js App Router?

Yes. Import it like any other React component; keep interactive subtrees in client components when you need hooks or browser APIs, and leave static structure in server components where possible.

Can I customize toast with Tailwind CSS?

Zentauri UI exposes class-friendly variants and slots so you can extend styles with Tailwind utilities without fighting inline styles.

Is this Toast implementation accessible by default?

Primitives follow sensible defaults, but accessibility depends on how you label controls, manage focus, and wire keyboard handlers in your app. Validate critical flows with keyboard-only use and screen readers.