Feedback/Sonner

Sonner

An opinionated toast component for React.

Themed

When to Use

Use Sonner when you need to:

Provide brief, non-blocking feedback about a completed action (save, delete, send)
Show success or error states for asynchronous operations like API calls
Display dismissible notifications that do not require user interaction
Communicate status updates with loading, success, and error states via promise toasts
Offer undo functionality for reversible actions

When Not to Use

Persistent, critical messages that must be acknowledged - use Alert
Confirmations before destructive actions - use Alert Dialog
Complex content or forms - use Dialog
Inline validation feedback - use form-level error messages instead

Default

Basic toast notification with a message, description, and action button.

Toast Types

Different toast types for various use cases: default, success, info, warning, and error.

With Description

Toasts can include a secondary description for additional context.

With Action

Add an action button to toasts for user interaction like undo or retry.

Promise

Automatically update toast content based on promise resolution. Shows loading, success, or error states.

Click to see loading → success states (2 second delay)

Custom Options

Customize toast behavior with duration, persistence, and other options.

UX & Design Guidelines

Visual Hierarchy

Use toast() for neutral informational messages, toast.success() for positive confirmations, and toast.error() for failures. Enable richColors on the Toaster to provide stronger visual distinction between toast types using semantic background colors.

Spacing & Layout

Toast notifications stack vertically with automatic spacing. Position toasts in bottom-right for standard applications or top-center for prominent notifications. Keep toast messages concise (under 100 characters) and add a description for supplementary details.

Responsive Behavior

Sonner automatically adapts to mobile viewports, rendering toasts full-width at the bottom of the screen. On desktop, toasts appear in the configured position with a fixed max-width. Ensure action labels are short enough to fit on smaller screens without truncation.

Color & Contrast

Toast backgrounds use --popover and --popover-foreground tokens for proper contrast in both light and dark modes. When richColors is enabled, semantic colors (green for success, red for error) meet WCAG 2.1 AA contrast requirements. The border radius inherits from the global --radius token.

Accessibility

Keyboard Navigation

Tab — Move focus to the toast when it appears
Enter or Space — Activate the action button within a toast
Escape — Dismiss the currently focused toast
When closeButton is enabled, it is reachable via Tab

Screen Reader Support

Toasts are announced via an ARIA live region (role="status")
New toasts are announced automatically without interrupting the current reading flow
Action buttons within toasts include accessible labels
Descriptions provide additional context read by assistive technology

Focus Management

Toasts do not steal focus from the current workflow. When a toast includes interactive elements (action buttons, close button), users can Tab into the toast. Focus returns to the previously focused element when the toast is dismissed. The close button uses a visible focus ring with focus-visible:ring-[3px].

Timing Considerations

The default 4-second duration provides enough time for most users to read the toast content. For important messages, increase duration or use duration: Infinity to keep the toast visible until manually dismissed. Users who need more time can hover over toasts to pause the auto-dismiss timer.

ARIA Attributes

{/* Toaster with theme syncing for proper contrast */}
<Toaster
  theme="system"
  richColors
  closeButton
/>

{/* Toast with descriptive message */}
toast("File uploaded successfully", {
  description: "report-2024.pdf has been saved to Documents.",
})

{/* Toast with action for undo capability */}
toast("Message deleted", {
  action: {
    label: "Undo",
    onClick: () => restoreMessage(),
  },
})

API Reference

The Toaster component accepts the following props for global toast configuration.

Prop	Type	Default	Description
theme	`"light" \| "dark" \| "system"`	"system"	The theme of the toasts. Automatically syncs with next-themes.
position	`"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"`	"bottom-right"	The position where toasts appear on the screen.
richColors	`boolean`	false	Enable rich colors for different toast types (success, error, etc.).
expand	`boolean`	false	Toasts will be expanded by default instead of stacking.
duration	`number`	4000	Default duration in milliseconds for all toasts.
closeButton	`boolean`	false	Show a close button on each toast.
icons	`Record<string, ReactNode>`	—	Custom icons for each toast type (success, info, warning, error, loading).
className	`string`	—	Additional CSS classes to apply to the toaster container.

Toast Methods

Available methods for displaying different types of toasts.

Prop	Type	Default	Description
toast(message)	`function`	—	Display a default toast notification.
toast.success(message)	`function`	—	Display a success toast with a checkmark icon.
toast.info(message)	`function`	—	Display an info toast with an info icon.
toast.warning(message)	`function`	—	Display a warning toast with a warning icon.
toast.error(message)	`function`	—	Display an error toast with an error icon.
toast.promise(promise, options)	`function`	—	Display a toast that updates based on promise state (loading, success, error).