Sonner-Style Toasts in Vanilla JavaScript – vanilla-sonner

vanilla-sonner is a framework-free JavaScript library for Sonner-style toast notifications.

It keeps loading messages visible as tasks progress, updates their status in place, and lets your app set capacity and overflow rules for each stack.

Features

• Success, info, warning, error, and loading notifications.
• In-place toast updates and animated or immediate dismissal.
• Promise-based messages and controlled upload progress.
• Per-position capacity limits and configurable overflow policies.
• Action buttons, swipe dismissal, and keyboard navigation.
• Custom HTML templates for trusted content.
• Independent toaster instances and message deduplication.
• Light, dark, and system themes, rich colors, and CSS styling hooks.

How To Use It

Basic Usage

Load the stylesheet and UMD script, then place <ol id="sonner-toast-container"> in the page before calling toast().

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Toast Notification Example</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/vanilla-sonner.min.css">
</head>
<body>
  <button id="save-settings" type="button">Save settings</button>
  <ol id="sonner-toast-container" position="bottom-right" duration="4000"></ol>
  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/vanilla-sonner.umd.min.js"></script>
  <script>
    document.querySelector('#save-settings').addEventListener('click', () => {
      toast.success('Settings saved.');
    });
  </script>
</body>
</html>

Install with npm

For a bundler-based project, install the package and import its stylesheet.

npm install vanilla-sonner

import { toast } from 'vanilla-sonner';
import 'vanilla-sonner/style.css';
toast.success('Changes saved.');
toast.message('Update available', 'Restart to apply the new version.');

Display Status Messages

The standard helpers accept a message and an optional per-toast configuration object. toast.message() takes a title, a description, and an optional configuration object.

toast('Message saved.');
toast.info('Sync started.');
toast.success('Export complete.');
toast.warning('Storage is almost full.');
toast.error('Could not save your changes.');
toast.message('Update ready', 'Restart the application to install it.');

Update a Loading Toast

Use the ID returned by toast.loading() to update progress and finish the notification in place. Progress accepts a number from 0 to 1. The example calls an application-defined uploadFile(callback) function that returns a promise and reports uploaded bytes and total bytes.

async function uploadReport(uploadFile) {
  const uploadId = toast.loading('Uploading report...', { progress: 0 });
  try {
    await uploadFile((loaded, total) => {
      if (total <= 0) return;
      const progress = loaded / total;
      toast.update(uploadId, {
        progress,
        message: `Uploading ${Math.round(progress * 100)}%`
      });
    });
    toast.done(uploadId, {
      message: 'Report uploaded.',
      duration: 3000
    });
  } catch {
    toast.update(uploadId, {
      type: 'error',
      message: 'Upload failed.',
      duration: 6000
    });
  }
}

Show Toasts for Promises

toast.promise() displays loading feedback and updates the notification when an existing promise settles. It returns the original promise, which can reject and should be handled by the caller. A short delay avoids flashing a loading message for fast requests. Results from previously dismissed or manually updated toasts are ignored. Since fetch() resolves for HTTP error responses, check response.ok to display an error toast for unsuccessful requests.

async function loadProfile() {
  const request = fetch('/api/profile').then(response => {
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response;
  });
  return toast.promise(request, {
    loading: 'Loading profile...',
    success: () => 'Profile loaded.',
    error: (error) => ({
      message: 'Could not load profile.',
      description: error instanceof Error ? error.message : 'Unknown error',
      duration: 8000
    })
  }, { delay: 250 });
}

Create a Custom HTML Toast

Standard toast messages, descriptions, and action labels render as text. For HTML markup, define a <template> and pass its ID to toast.custom(). Placeholders use simple {{ key }} tokens, and {{ id }} contains the current toast element ID.

<template id="connection-toast">
  <div>
    <strong>Connected to {{ network }}</strong>
  </div>
</template>

toast.custom('connection-toast', { network: 'Office Wi-Fi' }, {
  duration: 4000
});

Add an Action Button

An action can run a synchronous or asynchronous callback. The toast closes after the action completes unless the handler returns false. This example expects restoreArchivedMessage() to be defined in the application.

toast('Message archived.', {
  duration: 8000,
  action: {
    label: 'Undo',
    onClick: async () => {
      await restoreArchivedMessage();
    }
  }
});

Configure Separate Notification Stacks

Use createToaster() for a notification area with independent settings. It accepts a CSS selector or an HTMLElement as its first argument and an optional ToasterConfig object as its second. A unique id also lets the global API find that instance. Call destroy() when removing the instance’s application area.

<ol id="critical-alerts"></ol>

import { createToaster, toast } from 'vanilla-sonner';
const alerts = createToaster('#critical-alerts', {
  id: 'alerts',
  position: 'top-center',
  defaults: {
    error: { important: true, duration: 0 }
  }
});
alerts.error('Connection lost.');
toast.for('alerts').warning('Trying to reconnect...');
toast.info('Sent to alerts.', { toasterId: 'alerts' });

Configure Toast Stacking and Timing

Set global defaults with toast.configure(), either before the first toast or while the page is running. Each effective screen position has its own maxToasts capacity. The queue policy displays the oldest pending notifications first and pauses the timers of those waiting.

toast.configure({
  maxToasts: 3,
  overflow: 'queue',
  position: 'bottom-end',
  theme: 'system',
  hotkey: 'Alt+T',
  defaults: {
    default: { duration: 4000 },
    success: { duration: 2500 },
    error: { duration: 8000, important: true },
    loading: { duration: 0 }
  }
});

Complete Configuration Reference

Per-Toast Options (`ToastConfig`)

Toaster Options (`ToasterConfig`)

Pass these options to createToaster() or use toast.configure() for the default toaster.

Overflow Policies

HTML Container Attributes

The default container uses <ol id="sonner-toast-container">. Configure its basic behavior through these HTML attributes. Queue policies, hooks, and other advanced settings require the JavaScript API.

Public JavaScript API

Toast Creation Methods

Creation Parameters

Lifecycle and Management Methods

Promise Results and Actions

Lifecycle Callbacks and Inspection

Deduplication and Creation Hooks

Configure toaster-wide duplicate filtering through dedupe: 'message', or supply a resolver that receives a proposed toast and active snapshots. Returning an existing toast ID reuses that ID. beforeCreate receives the proposed options and active snapshots. Return updated options to alter the new toast or false to reject it. The per-toast dedupe: false option overrides toaster-level duplicate checking for one call.

toast.configure({
  dedupe(next, active) {
    const previous = active.find(
      item => item.data?.requestId === next.data?.requestId
    );
    return previous?.id ?? false;
  },
  beforeCreate(next) {
    if (next.message === 'internal-only') return false;
    return { ...next, richColors: true };
  }
});

Styling and Customization

The stylesheet exposes stable data-sonner-part selectors for individual toast elements. Use these selectors for overrides.

unstyled: true removes built-in surface decoration but preserves toast positioning, interactions, and accessibility behavior. For custom layouts, load the library stylesheet first and apply your rules afterward.

Styling Parts

State Attributes

The toast markup also exposes the following state attributes for conditional CSS.

CSS Custom Properties

These CSS custom properties control the sizing and spacing controls of the default toast stylesheet.

Custom Style Example

Place custom rules after the library stylesheet to change toast width, padding, and stack spacing.

[data-sonner-part="toast"] {
  --width: 280px;
  --padding: 12px;
  --gap: 14px;
}

Accessibility and Keyboard Controls

Normal messages use a polite live region with role="status". An important: true notification uses assertive alert semantics. The default shortcut Alt+T focuses the newest visible notification. Arrow keys move between visible toasts, Escape dismisses the focused toast, and Tab reaches its buttons. Focus, hover, hidden documents, queued messages, and active swipes can pause dismissal timers independently.

toast.error('Payment failed.', { important: true });
toast.configure({ hotkey: 'Ctrl+Shift+N' });
// Use hotkey: false to disable the shortcut.

Alternatives and Related Resources

• Sonner-Style Stacked Toast Notifications in JavaScript – Toastry
• Simple Interactive Snackbar & Toast Notification In Vanilla JavaScript – notifyjs
• Toast-style Web Notifications In Vanilla JavaScript – VanillaToasts
• Vanilla JS Info/Warning/Error/Danger Toast Notification Library – Toasteur.js