Sonner API Reference
Exact props, types, and defaults. Options passed to toast() override the same options set via the Toaster's toastOptions.
<Toaster />
| Prop |
Type |
Default |
Description |
theme |
string |
'light' |
'light', 'dark', or 'system'. |
richColors |
boolean |
false |
Makes error and success states more colorful. |
expand |
boolean |
false |
Toasts expanded by default (otherwise they expand on hover). |
visibleToasts |
number |
3 |
Amount of visible toasts. |
id |
string |
– |
Toaster id, targeted by toast()'s toasterId option. |
position |
string |
'bottom-right' |
top-left, top-center, top-right, bottom-left, bottom-center, bottom-right. |
closeButton |
boolean |
false |
Adds a close button to all toasts. |
offset |
string | number | object |
'32px' |
Offset from screen edges. Object form is per-side: { bottom: '24px', right: '16px' }. |
mobileOffset |
string | number | object |
'16px' |
Offset when screen width < 600px. |
swipeDirections |
array |
based on position |
Allowed swipe-to-dismiss directions. |
dir |
string |
'ltr' |
Text directionality. |
hotkey |
string |
⌥/alt + T |
Keyboard shortcut that focuses the toaster area. |
invert |
boolean |
false |
Dark toasts in light mode and vice versa. |
toastOptions |
object |
– |
Default options applied to every toast (any toast() option below). |
gap |
number |
14 |
Gap between toasts when expanded. |
icons |
object |
– |
Replace default icons: { success, info, warning, error, loading }; null removes one. |
toast() options
toast(message, options) — message is a string, JSX, or a function returning JSX. Returns the toast's id.
| Option |
Type |
Default |
Description |
description |
ReactNode |
– |
Renders underneath the title; also accepts a function returning JSX. |
closeButton |
boolean |
false |
Adds a close button. |
invert |
boolean |
false |
Dark toast in light mode and vice versa. |
duration |
number |
4000 |
Milliseconds before auto-close. Infinity persists the toast. |
position |
string |
'bottom-right' |
Position of this toast. |
dismissible |
boolean |
true |
If false, the user cannot dismiss the toast. |
icon |
ReactNode |
– |
Icon in front of the text; null removes the default. |
action |
ReactNode | { label, onClick } |
– |
Primary button; clicking closes the toast unless onClick calls event.preventDefault(). |
cancel |
ReactNode | { label, onClick } |
– |
Secondary button; clicking closes the toast. |
actionButtonStyle |
object |
{} |
Styles for the action button. |
cancelButtonStyle |
object |
{} |
Styles for the cancel button. |
id |
string |
– |
Custom id; calling toast() again with the same id updates the existing toast. |
testId |
string |
– |
Rendered as data-testid for e2e tests. |
toasterId |
string |
– |
Id of the toaster to render this toast in. |
style |
object |
– |
Inline styles for the toast. |
classNames |
object |
– |
Classes per part: { toast, title, description, actionButton, cancelButton, closeButton }. Needs !important unless unstyled. |
unstyled |
boolean |
false |
Removes all default styles. |
onDismiss |
(toast) => void |
– |
Fires when the close button is clicked or the toast is swiped away. |
onAutoClose |
(toast) => void |
– |
Fires when the toast closes automatically after duration. |
containerAriaLabel |
string |
'Notifications' |
ARIA label for the toast container. |
Functions
| Function |
Purpose |
toast(message, opts?) |
Render a toast; returns its id. |
toast.success / .error / .info / .warning(message, opts?) |
Typed toast with matching icon. |
toast.loading(message, opts?) |
Toast with a spinner; update it by id. |
toast.promise(promise, { loading, success, error }) |
Loading toast that resolves with the promise; success/error accept strings, JSX, functions of the result, or objects of toast options. |
toast.custom((t) => jsx, opts?) |
Headless toast — your JSX, Sonner's behavior. |
toast.dismiss(id?) |
Dismiss one toast, or all when called without an id. |
toast.getActiveToasts() |
All active toasts, usable outside React. |
useSonner() |
React hook returning { toasts }. |