API reference

`<sonner-toaster>` attributes

Configure the host element via HTML attributes. All are optional.

Attribute	Values	Default	Description
`position`	`top-left` · `top-center` · `top-right` · `bottom-left` · `bottom-center` · `bottom-right`	`bottom-right`	Where toasts appear relative to the viewport.
`theme`	`light` · `dark` · `system`	`light`	Color theme. `system` tracks `prefers-color-scheme`.
`rich-colors`	boolean (presence)	off	Colored success / error / warning / info variants.
`close-button`	boolean (presence)	off	Show a close button on every toast.
`invert`	boolean (presence)	off	Flip background and text against the current theme.
`dir`	`ltr` · `rtl` · `auto`	`auto`	Text direction.
`gap`	number (px)	`14`	Spacing between stacked toasts when expanded.
`duration`	number (ms)	`4000`	Default lifetime; per-toast overrides win.
`visible-toasts`	number	`3`	How many toasts are fully visible before fading.
`offset`	CSS length	`24px`	Distance from viewport edges.
`mobile-offset`	CSS length	`16px`	Edge distance under 600px viewport width.
`hotkey`	chord string, `""`, or `"none"`	`altKey+KeyT`	Keyboard chord that expands the stack. Empty / `none` disables it.
`expand`	boolean (presence)	off	Force-expand the stack even without hover.
`container-aria-label`	string	`Notifications`	Accessible name for the toaster region. Reactive — changes after mount take effect.

`<sonner-toast>` attributes

Per-toast overrides — any of these on an individual toast wins over the toaster default.

Attribute	Values	Default	Description
`type`	`default` · `success` · `error` · `info` · `warning` · `loading`	`default`	Visual variant and built-in icon.
`duration`	number (ms) or `Infinity`	inherits toaster	How long before auto-dismiss.
`dismissible`	`false` to opt out	true	Whether close button + swipe dismiss this toast.
`position`	same as toaster	inherits toaster	Override position for one toast.
`close-button`	boolean	inherits toaster	Show close button on this toast.
`rich-colors`	boolean	inherits toaster	Force rich colors on this toast.
`invert`	boolean	inherits toaster	Force inverted colors on this toast.

`<sonner-toast>` slots

Slot	Purpose
`title`	Primary text.
`description`	Secondary text.
`icon`	Override the icon picked from `type`.
`action`	Right-aligned action button (e.g. Undo).
`cancel`	Left-aligned cancel button.
(default)	Used by `toast.custom()` for fully custom content.

`toast()` options

The second argument to toast() (and its variants) accepts:

Option	Type	Notes
`id`	`string \| number`	Reuse to update a toast in place.
`toasterId`	`string`	DOM `id` of a specific `<sonner-toaster>` to route this toast to. Falls back to the default toaster if no match.
`testId`	`string`	Set as `data-testid` on the toast host. Survives promise transitions.
`closeButtonAriaLabel`	`string`	Accessible name for the close button. Defaults to `Close: <title>`.
`description`	`string \| Node \| () => …`	Secondary text.
`duration`	`number` or `Infinity`	Lifetime override (ms).
`dismissible`	`boolean`	Set `false` to disable swipe / close-button dismissal.
`position`	same as toaster	Per-toast position override.
`closeButton`	`boolean`	Per-toast override of the toaster's `close-button` flag.
`richColors` / `invert`	`boolean`	Force the variant on this toast.
`icon`	`Node \| string`	Override the icon picked from `type`.
`className`	`string`	Extra class applied to the toast host.
`action` / `cancel`	`{ label, onClick }` or `HTMLElement`	Right / left button. Pass an element for full control.
`onDismiss` / `onAutoClose`	`(el) => void`	Lifecycle callbacks.

The `toast()` function

import { toast } from 'sonner-wc';

toast('Default message');
toast.success('Saved');
toast.error('Oops');
toast.info('FYI');
toast.warning('Heads up');
toast.loading('Working…', { duration: Infinity });
toast.message('Same as toast(), explicit form');

`toast.promise()`

toast.promise(savePost(), {
  loading: 'Saving…',
  success: (data) => `Saved "${data.title}"`,
  error: (err) => `Failed: ${err.message}`,
});

`toast.custom()`

toast.custom((id) => {
  const el = document.createElement('div');
  el.textContent = `Custom toast #${id}`;
  return el;
});

`toast.dismiss()`

Use the same id to update an existing toast in place. Pass no argument to dismiss everything.

const id = toast.loading('Working…');
// later…
toast.dismiss(id);

// or dismiss everything
toast.dismiss();

// update a toast in place by reusing its id
toast.loading('Working…', { id: 'job-1' });
toast.success('Done', { id: 'job-1' });

Events

Each toast dispatches the following bubbling, composed CustomEvents:

Event	When
`sonner-toast-mounted`	After the mount transition begins.
`sonner-toast-updated`	After `update()` applies (used by `toast.promise`).
`sonner-toast-dismissed`	When `dismiss()` is called (before the exit animation finishes).
`sonner-toast-autoclosed`	When the auto-dismiss timer fires.

API reference

<sonner-toaster> attributes

<sonner-toast> attributes

<sonner-toast> slots

toast() options

The toast() function

toast.promise()

toast.custom()

toast.dismiss()