Toast
Toasts acknowledge short-lived product events without interrupting the current workflow.
Overview and decision boundary
Use Toast to acknowledge short-lived product events without blocking the workflow.
Do not use Toast for destructive confirmations or blocking errors.
Preview
import { Button, ToastProvider, ToastViewport, useToastManager } from '@nerio-ui/ui/client';function Example() { const toasts = useToastManager(); return ( <Button onClick={() => toasts.add({ id: "save-result", title: "Saved", description: "The collection is available to your team.", timeout: 5000, // Use 0 only for an intentionally persistent toast. priority: "low", data: { tone: "success" }, })}> Show toast </Button> );}<ToastProvider limit={3}> <Example /> <ToastViewport label="Notifications" /></ToastProvider>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm dlx nerio add toastimport { Button, ToastProvider, ToastViewport, useToastManager } from '@nerio-ui/ui/client';Usage
import { Button, ToastProvider, ToastViewport, useToastManager } from '@nerio-ui/ui/client';function Example() { const toasts = useToastManager(); return ( <Button onClick={() => toasts.add({ id: "save-result", title: "Saved", description: "The collection is available to your team.", timeout: 5000, // Use 0 only for an intentionally persistent toast. priority: "low", data: { tone: "success" }, })}> Show toast </Button> );}<ToastProvider limit={3}> <Example /> <ToastViewport label="Notifications" /></ToastProvider>Variants
| Variant | Purpose |
|---|---|
neutral | Low-emphasis status or message. |
info | Informational state that should stay calm. |
success | Positive completion or validation state. |
warning | Warning state that needs attention without blocking the whole flow. |
danger | Error, destructive, or blocking state. |
Anatomy
| Slot | Purpose |
|---|---|
viewport | Portal layer where toasts are announced and positioned. |
root | Root slot exposed through data-slot="root". |
content | Content slot exposed through data-slot="content". |
status-indicator | Status Indicator slot exposed through data-slot="status-indicator". |
title | Title slot exposed through data-slot="title". |
description | Description slot exposed through data-slot="description". |
action | Action slot exposed through data-slot="action". |
close | Close slot exposed through data-slot="close". |
States
| State | Purpose |
|---|---|
Timed | Auto-dismisses after the provider or toast timeout. |
Persistent | Uses timeout 0 and always keeps a dismiss path. |
Paused | Preserves remaining time during pointer, keyboard focus, or window blur. |
Swiping | Dismisses past the threshold and returns to position when cancelled. |
Expanded stack | Expands upward from a bottom-centered stack whose collapsed cards scale and step upward behind the frontmost toast. |
Limited | Keeps overflow mounted but inert and visually hidden. |
Motion
- State changes should use shared motion tokens and preserve reduced-motion behavior.
Accessibility
- Uses the Base UI Toast primitive and manager.
- Use low priority for routine polite confirmations and high priority only for urgent updates.
- Base UI announces managed title and description once; decorative status icons and action copy are excluded from the announcement.
- Static Toast remains presentation-only and separate from managed status and stack behavior; managed actions and icon-only dismissal use Button.
- The managed viewport is bottom-centered; collapsed toasts scale and step upward behind the frontmost card, then expand upward without changing reading order.
- Managed toasts never steal focus. F6 enters the viewport, where actions and dismissal remain keyboard reachable.
- Timers pause on pointer hover, keyboard focus, and window blur, then resume from the remaining duration. Set timeout to 0 only for an intentionally persistent toast.
- Inherited document direction is resolved for the first interactive render and remains synchronized with root dir changes; explicit direction wins immediately.
- Swipe supports pointer and touch input, logical RTL direction, four physical dismissal directions, cancellation, and reduced motion without replacing the dismiss control.
- Use one provider per managed stack. Pass a manager from createToastManager only when an independent second provider is intentional.
- Keep messages concise and avoid replacing persistent error UI with a toast.
API
| Prop | Purpose |
|---|---|
ToastProvider | Wraps one managed stack and configures limit, default timeout, and an optional independent manager. |
ToastViewport | Safe-area portal target with localized landmark/dismiss labels and RTL-aware swipe direction. |
useToastManager | Adds, updates, replaces, and removes messages; duplicate IDs update in place and refresh their timer. |
createToastManager | Creates an isolated manager when an application intentionally needs another provider. |
timeout | Milliseconds before dismissal; 0 creates a persistent toast. |
priority | low is polite; high is reserved for urgent announcements. |
dismissText | Localizes the managed dismiss Button tooltip. |
dismissLabel | Localizes the managed dismiss Button accessible name. |
direction | Overrides inherited document direction immediately with ltr or rtl. |
swipeDirection | Accepts physical directions or logical inline-start and inline-end directions resolved from the viewport direction. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | toast installs 6 source files into the configured components directory. |
Base UI | toast |
Registry dependencies | button |
Package dependencies | @base-ui/react, @nerio-ui/adapters, clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Toast is an inverted dark glass surface in every mode so transient feedback is clearly separated from flat page content.
- Semantic color is limited to the status icon; copy and controls use the toast foreground hierarchy.
Do / do not
Do
Confirm short-lived background events like saved, copied, or sent.
Use one provider and viewport per managed stack; create a separate manager only for an intentionally isolated stack.
Do not
Do not use Toast for destructive confirmations or blocking errors.
Do not turn Toast into a notification inbox, activity feed, job manager, or persistent history.
Related components
Tokens
These are the primary customization points. Override semantic or component tokens instead of changing component source.
| Token | Purpose |
|---|---|
--n-toast-width | Public customization point for this component contract. |
--n-toast-viewport-inset | Public customization point for this component contract. |
--n-toast-stack-gap | Public customization point for this component contract. |
--n-toast-stack-offset | Public customization point for this component contract. |
--n-toast-stack-scale-step | Public customization point for this component contract. |
--n-toast-enter-offset | Public customization point for this component contract. |
--n-toast-swipe-dismiss-distance | Public customization point for this component contract. |
--n-overlay-z-index | Public customization point for this component contract. |
--n-toast-background | Public customization point for this component contract. |
--n-toast-border | Public customization point for this component contract. |
--n-toast-shadow | Public customization point for this component contract. |
--n-toast-foreground | Public customization point for this component contract. |
--n-toast-foreground-muted | Public customization point for this component contract. |
--n-toast-control-background | Public customization point for this component contract. |
--n-toast-control-background-hover | Public customization point for this component contract. |
--n-toast-control-background-active | Public customization point for this component contract. |
--n-toast-status-color | Public customization point for this component contract. |
--n-toast-status-info | Public customization point for this component contract. |
--n-toast-status-success | Public customization point for this component contract. |
--n-toast-status-warning | Public customization point for this component contract. |
--n-toast-status-danger | Public customization point for this component contract. |
--n-motion-reveal-duration | Public customization point for this component contract. |
--n-motion-reveal-easing | Public customization point for this component contract. |
--n-motion-focus-duration | Public customization point for this component contract. |
--n-motion-focus-easing | Public customization point for this component contract. |
--n-focus-ring | Public customization point for this component contract. |