Feedback/Toast

Toast

A succinct message that is displayed temporarily.

Not Started

When to Use

Use Toast when you need to:

Provide brief feedback after a user action (save, delete, send)
Confirm that a background process completed successfully
Display non-critical warnings or informational messages
Offer an undo action for a recently performed operation
Show async operation status (loading, success, error)

When Not to Use

Critical errors requiring user action - use Alert Dialog
Persistent status messages - use Alert inline in the page
Confirmation dialogs before destructive actions - use Dialog
Form validation errors - display errors inline near the relevant fields

Default

The default toast with a message, description, and action button.

Types

Different toast types for various feedback contexts: default, success, info, warning, and error.

With Description

Toasts with secondary descriptive text for additional context.

With Action

Toasts with action buttons for undo, retry, or other follow-up actions.

Promise

Async toast that shows loading, success, and error states automatically.

Click to see loading, then success states (2 second delay)

Custom Duration

Control how long toasts remain visible, including persistent toasts that require manual dismissal.

Positions

Configure where toasts appear on screen by setting the position prop on the Toaster component.

Configure the position via the position prop on the Toaster component in your layout.

UX & Design Guidelines

Visual Hierarchy

Use toast() for neutral feedback, toast.success() for positive confirmations, toast.warning() for caution, and toast.error() for failures. Each type has distinct icon and color treatment for quick visual scanning.

Spacing & Layout

Toasts stack vertically with consistent spacing. The Toaster component manages layout automatically. Keep toast messages concise (under 2 lines) to avoid obscuring page content. Action labels should be short (1-2 words) like "Undo", "Retry", or "View".

Responsive Behavior

On mobile, toasts expand to full width with adequate touch targets for action buttons. Consider using position="top-center" on mobile to avoid conflicts with bottom navigation bars. The default visibleToasts of 3 prevents screen overwhelm on smaller viewports.

Color & Contrast

Toast backgrounds use --popover and --popover-foreground for consistent theming. Type-specific icons (success, error, warning, info) use semantic colors that meet WCAG 2.1 AA contrast ratios. The border uses --border for subtle separation from the background.

Accessibility

Keyboard Navigation

Tab — Move focus to the toast action button when visible
Enter or Space — Activate the action button
Escape — Dismiss the currently focused toast

Screen Reader Support

Toasts use role="status" with aria-live="polite" to announce messages without interrupting the user
Error toasts use aria-live="assertive" for immediate announcement
Description text provides additional context that is read after the main message
Action buttons are announced with their label text

Focus Management

Toasts do not steal focus from the current interaction. Action buttons within toasts are focusable via Tab key. When a toast is dismissed, focus returns to the previously focused element. Persistent toasts (with duration: Infinity) should always include a dismiss action for keyboard users.

Timing Considerations

The default 4-second duration provides adequate reading time for most messages. For longer messages or toasts with actions, increase the duration or use duration: Infinity. Users who need more time can hover over a toast to pause the auto-dismiss timer.

ARIA Attributes

{/* Toasts are announced by screen readers via role="status" */}
<Toaster />

{/* Toast with descriptive message */}
toast.success("File uploaded successfully", {
  description: "document.pdf has been saved to your files.",
})

{/* Toast with action button for undo pattern */}
toast("Item deleted", {
  action: {
    label: "Undo",
    onClick: () => restoreItem(),
  },
  description: "The item has been moved to trash.",
})

{/* Error toast with retry action */}
toast.error("Upload failed", {
  description: "Check your connection and try again.",
  action: {
    label: "Retry",
    onClick: () => retryUpload(),
  },
})

API Reference

The Toast system consists of a Toaster component and a toast() function for triggering notifications.

Toaster Component Props

Prop	Type	Default	Description
position	`"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"`	"bottom-right"	The position where toasts appear on screen.
theme	`"light" \| "dark" \| "system"`	"system"	The color theme for the toast. Automatically synced with next-themes.
richColors	`boolean`	false	When true, uses colorful backgrounds for different toast types.
expand	`boolean`	false	When true, toasts are expanded by default instead of stacked.
duration	`number`	4000	Default duration in milliseconds before toasts auto-dismiss.
visibleToasts	`number`	3	Maximum number of toasts visible at once.
closeButton	`boolean`	false	When true, adds a close button to each toast.
icons	`ToasterProps['icons']`	—	Custom icons for success, info, warning, error, and loading states.
className	`string`	—	Additional CSS classes to apply to the toaster container.

toast() Function Options

Prop	Type	Default	Description
messagerequired	`string \| React.ReactNode`	—	The main content of the toast notification.
description	`string \| React.ReactNode`	—	Secondary text displayed below the main message.
action	`{ label: string; onClick: () => void }`	—	An action button displayed in the toast.
duration	`number`	4000	Duration in milliseconds before the toast auto-dismisses. Use Infinity for persistent toasts.
id	`string \| number`	—	A unique ID for the toast. Useful for updating or dismissing specific toasts.
onDismiss	`(toast: Toast) => void`	—	Callback fired when the toast is dismissed.
onAutoClose	`(toast: Toast) => void`	—	Callback fired when the toast auto-closes after the duration.