Vanilla Toast

A lightweight, standalone toast notification library for Vanilla JavaScript. Vanilla Toast ships with TypeScript types, CDN-ready bundles, smooth stacked animations, promise handling, swipe dismissal, accessible controls, and zero framework dependencies.

Installation

npm install vanilla-toast-js

CDN Usage

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vanilla-toast-js/dist/vanilla-toast.css" />
<script src="https://cdn.jsdelivr.net/npm/vanilla-toast-js/dist/vanilla-toast.iife.js"></script>
<script>
  vanillaToast.success('Saved!');
</script>

The browser bundle exposes window.vanillaToast, window.VanillaToast.toast, and the convenience alias window.toast.

UNPKG Usage

<link rel="stylesheet" href="https://unpkg.com/vanilla-toast-js/dist/vanilla-toast.css" />
<script src="https://unpkg.com/vanilla-toast-js/dist/vanilla-toast.iife.js"></script>
<script>
  vanillaToast.success('Saved!');
</script>

NPM Usage

import { toast } from 'vanilla-toast-js';
import 'vanilla-toast-js/style.css';

toast.success('Saved!');

Basic Examples

toast('Event created');

toast('Event created', {
  description: 'Sunday at 9:00 AM',
  closeButton: true,
});

Toast Types

toast('Default message');
toast.success('Saved');
toast.error('Failed');
toast.warning('Check your input');
toast.info('New version available');
toast.loading('Uploading...');

Positioning

Each position gets an independent container and stack.

toast.success('Top right', { position: 'top-right' });
toast.info('Bottom center', { position: 'bottom-center' });

Supported positions:

• top-left
• top-center
• top-right
• bottom-left
• bottom-center
• bottom-right

Close Button

toast.success('Saved', {
  closeButton: true,
});

Enable close buttons globally:

toast.configure({
  closeButton: true,
});

Close buttons are keyboard focusable and use aria-label="Close notification".

Progress Bar

The progress bar mirrors the auto-dismiss timer. It pauses while the stack is hovered or while focus is inside a toast, then resumes when interaction leaves.

toast.info('Syncing...', {
  duration: 6000,
  progressBar: true,
});

Disable it per toast:

toast('Plain message', {
  progressBar: false,
});

Promise Toasts

toast.promise(fetch('/api/save'), {
  loading: 'Saving...',
  success: 'Saved!',
  error: 'Save failed',
});

Messages may be strings, option objects, or functions.

toast.promise(loadUser(), {
  loading: { title: 'Loading user...', closeButton: true },
  success: (user) => `Welcome ${user.name}`,
  error: (error) => ({
    title: 'Unable to load user',
    description: String(error),
  }),
});

Update Toasts

const id = toast.loading('Uploading...', {
  closeButton: true,
});

toast.update(id, {
  title: 'Upload complete',
  type: 'success',
  duration: 3000,
});

Updates preserve the toast id and rebuild event listeners safely.

Dismiss Toast

const id = toast.success('Saved');

toast.dismiss(id);

Dismissal plays the exit animation, clears timers, removes listeners, removes the DOM node, and updates the stack.

Dismiss All

toast.dismissAll();

toast.dismiss() with no id is also supported for compatibility.

Configuration

toast.configure({
  position: 'bottom-right',
  duration: 4000,
  richColors: false,
  closeButton: true,
  progressBar: true,
  maxVisible: 5,
  theme: 'system',
  animation: 'slide',
  pauseOnHover: true,
  swipeToDismiss: true,
  keyboardDismiss: true,
  expandOnHover: true,
});

Themes

toast.configure({
  theme: 'dark',
});

Supported themes:

• light
• dark
• system

Customize with CSS variables:

:root {
  --vt-bg: #ffffff;
  --vt-color: #171717;
  --vt-border: #e8e8e8;
  --vt-gap: 14px;
  --vt-width: 356px;
  --vt-radius: 8px;
  --vt-shadow: 0 10px 32px rgba(0, 0, 0, 0.12);
  --vt-z-index: 999999;
}

Animations

toast.success('Saved', {
  animation: 'bounce',
});

Supported animations:

• slide
• fade
• scale
• bounce

Animations use GPU-friendly transforms and respect prefers-reduced-motion.

TypeScript Support

Types are included and exported from the package.

import type {
  ToastId,
  ToastOptions,
  ToastPosition,
  ToasterOptions,
  VanillaToastOptions,
} from 'vanilla-toast-js';

const options: ToastOptions = {
  position: 'top-right',
  closeButton: true,
};

API Reference

toast(message: string, options?: ToastOptions): ToastId;
toast.success(message: string, options?: ToastOptions): ToastId;
toast.error(message: string, options?: ToastOptions): ToastId;
toast.warning(message: string, options?: ToastOptions): ToastId;
toast.info(message: string, options?: ToastOptions): ToastId;
toast.loading(message: string, options?: ToastOptions): ToastId;
toast.custom(element: HTMLElement, options?: ToastOptions): ToastId;
toast.update(id: ToastId, options: ToastUpdateOptions): void;
toast.dismiss(id?: ToastId): void;
toast.dismissAll(): void;
toast.promise<T>(promise: Promise<T> | (() => Promise<T>), messages: ToastPromiseMessages<T>, options?: ToastOptions): Promise<T>;
toast.configure(options: Partial<ToasterOptions>): void;

Migration from vanilla-toast

Replace:

npm install vanilla-toast

with:

npm install vanilla-toast-js

Replace:

import { toast } from 'vanilla-toast';

with:

import { toast } from 'vanilla-toast-js';

Import the CSS once in your app entry:

import 'vanilla-toast-js/style.css';

FAQ

Does Vanilla Toast require a framework?

No. It works with plain HTML, Vite, Astro, Laravel, Rails, static sites, and framework apps.

Can I use it from a CDN?

Yes. Include https://cdn.jsdelivr.net/npm/vanilla-toast-js/dist/vanilla-toast.css and https://cdn.jsdelivr.net/npm/vanilla-toast-js/dist/vanilla-toast.iife.js, or use the matching UNPKG URLs.

Can users dismiss with the keyboard?

Yes. Close buttons are native buttons, and Escape dismisses the newest active toast by default.

Can I disable swipe dismissal?

Yes.

toast.configure({ swipeToDismiss: false });

Examples

Action toast:

toast('File deleted', {
  action: {
    label: 'Undo',
    onClick: () => restoreFile(),
  },
  closeButton: true,
});

Rich color toast:

toast.error('Payment failed', {
  description: 'Please check your card details.',
  richColors: true,
});

Persistent loading toast:

const id = toast.loading('Processing...', {
  duration: Infinity,
});

Browser Support

Vanilla Toast targets modern evergreen browsers and uses standard DOM APIs, CSS custom properties, pointer events, and requestAnimationFrame.

License

MIT