Sonner

v1.0.0 | View in Storybook

​

When to use

• To provide timely feedback for user-triggered actions (e.g., “Item deleted.”).
• For non-critical updates that don’t require immediate attention (e.g., “2 new messages.”).
• To confirm or acknowledge system or app processes (e.g., “Downloading file…”).
• When you need a lightweight, non-disruptive notification that doesn’t block user progress.
• To display multiple messages in sequence without breaking the user flow.

​

When to use something else

• Urgent, blocking issues: use Dialog, Alert dialog, or Banner.
• Long or detailed content, or must-stay-visible feedback: use inline validation, Alert, or dedicated error regions—not a toast.
• Persistent system-level messaging: prefer Banner; task-scoped feedback: prefer Alert.

​

Dos and don’ts

• Do keep messages short and clear (1-2 lines max).
• Do use appropriate semantic status color and iconography to convey status (e.g., success = green, warning = yellow).
• Do provide an “Undo” or “Retry” action if possible.
• Don’t show vague or generic messages (e.g., “Done” or “Failed”).
• Don’t display more than one Sonner at a time.

​

Behavior

There is a priority-based queue and duration of display time depending on the feedback type. The counter ensures that more critical Sonners stay on the screen for a longer period of time, giving the user more chance to read and act on them. Sonners have a minimum display time of 4 seconds. Dismissal: Auto-dismiss: Sonners automatically disappear after their display time (see table above). Manual dismiss (optional): You can include a close Button for user control, especially for longer or persistent messages.

​

Often used with

Optional action control (e.g. Undo) styled as a Button; status icon; does not include full Alert copy blocks.

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

With description

Add a description when the toast message needs a brief supporting detail—for example, explaining what was saved or what happens next after an action.

​

Success

Use a success toast to confirm a completed action—for example, “Item saved” or “Changes published”—so users know the operation finished without blocking their workflow.

​

Error state

Use an error toast for non-blocking failures—for example, a network timeout or validation issue where the user can retry without leaving the current page.

​

Warning

Use a warning toast when something needs attention but does not block progress—for example, a partial save or a setting that may have unintended side effects.

​

Info

Use an info toast for neutral updates that do not indicate success or failure—for example, background sync status or informational notices about app behavior.

​

With action

Add an action button when users may want to undo, retry, or navigate to related content—for example, “Undo” after deleting an item or “View” after a background task completes.

​

Long title with action

Use a longer title with an action when the message needs more context but should still stay concise—keep copy to one or two lines and place the action on the right.

​

Long title warning

Use a longer warning title when the message needs more context, but keep copy brief and actionable so users can read it before the toast auto-dismisses.

​

Title beyond two lines

Avoid titles longer than two lines in production—this example shows how overflow is handled, but keep real messages short for readability and auto-dismiss timing.

​

With cancel button

Add a cancel button when the toast represents an in-progress action users may want to stop—for example, cancelling an upload or a background sync.

​

With close button

Add a close button when users should be able to dismiss the toast before it auto-dismisses—for example, longer messages or toasts that stay visible longer.

​

Action and close button

Combine an action and close button when users need both a quick follow-up and manual dismiss—for example, “Undo” alongside the option to close without acting.

​

Icon visibility by description

Icon visibility adjusts based on whether a description is present—use descriptions when the status needs clarification beyond what the icon alone conveys.