Toastry

Installation

Get started in under a minute.

npm

npm install @oddsrabbit/toastry

CDN (script tag)

<script src="https://unpkg.com/@oddsrabbit/toastry@1/dist/toastry.js"></script>

<script>
  toast('Hello world');
</script>

ES Modules

import toast from '@oddsrabbit/toastry';

toast('Hello world');

CSS is auto-injected. A standalone file is also available at @oddsrabbit/toastry/css if needed.

API Reference

Every method Toastry provides.

toast(message, options?)

Show a default toast. Returns a numeric ID you can use to dismiss it later.

toast('Hello world');

// With options
toast('Check this out', {
  description: 'A longer explanation below the title.',
  duration: 5000,
});

toast.success(message, options?)

Green checkmark toast for success states.

toast.success('Saved successfully');

toast.error(message, options?)

Red X toast for error states.

toast.error('Something went wrong');

toast.warning(message, options?)

Yellow triangle toast for warnings.

toast.warning('Are you sure?');

toast.info(message, options?)

Blue info circle toast for informational messages.

toast.info('New update available');

toast.loading(message, options?)

Spinner toast that stays visible until manually dismissed. Does not auto-dismiss.

const id = toast.loading('Uploading...');

// When done:
toast.dismiss(id);

toast.promise(promise, states)

Automatically transitions from loading to success or error based on promise resolution. Returns the original promise.

toast.promise(saveData(), {
  loading: 'Saving...',
  success: 'Saved!',
  error: 'Could not save',
});

// Dynamic messages based on result
toast.promise(fetchUser(), {
  loading: 'Loading user...',
  success: (user) => `Welcome, ${user.name}!`,
  error: (err) => `Error: ${err.message}`,
});

toast.dismiss(id?)

Dismiss a specific toast by ID, or dismiss all toasts if no ID is provided.

const id = toast('Hello');
toast.dismiss(id);     // Dismiss one
toast.dismiss();       // Dismiss all

toast.configure(options)

Set global defaults. Call once at app startup.

toast.configure({
  position: 'top-right',    // 'bottom-right' (default) | 'bottom-left' | 'top-right' | 'top-left'
  duration: 5000,            // Duration in ms, default: 4000 (0 = no auto-dismiss)
  maxVisible: 5,             // Max visible toasts when collapsed (default: 3)
  maxToasts: 8,              // Max total toasts before oldest are pruned (default: 5)
  clearAll: true,            // Show a "Dismiss all" button beside a stack of 2+ toasts (default: false)
  clearAllLabel: 'Clear',     // Button label (default: 'Dismiss all')
});

toast.dismissAll()

Dismiss every toast except loading ones, which stand for work still in flight. This is what the clearAll button calls. The button shows when the stack expands (on hover or keyboard focus), or always on touch devices.

toast.dismissAll();

Options Object

Passed as the second argument to any toast method.

toast('File deleted', {
  description: 'The file has been moved to trash.',
  duration: 6000,
  icon: 'https://example.com/icon.png',  // Custom image URL (overrides type icon)
  action: {
    label: 'Undo',
    onClick: () => toast.success('Restored!'),
  },
});

Customization

Override CSS variables to match your theme.

Variable	Default	Description
--toastry-bg	#fff	Toast background
--toastry-border	#e5e5e5	Toast border
--toastry-text	#171717	Title text color
--toastry-text-muted	#6b7280	Description text color
--toastry-text-faint	#9ca3af	Close button color
--toastry-accent	#2563eb	Info icon & action text
--toastry-success	#16a34a	Success icon color
--toastry-error	#dc2626	Error icon color
--toastry-warning	#f59e0b	Warning icon color
--toastry-close-hover-bg	#f3f4f6	Close button hover bg
--toastry-action-border	#e5e7eb	Action button border
--toastry-action-border-hover	#d1d5db	Action button hover border
--toastry-spinner-track	#e5e7eb	Loading spinner track
--toastry-font	system-ui, -apple-system, sans-serif

Dark Mode Example

@media (prefers-color-scheme: dark) {
  :root {
    --toastry-bg: #1c1c1c;
    --toastry-border: #333;
    --toastry-text: #f5f5f5;
    --toastry-text-muted: #a1a1aa;
    --toastry-text-faint: #71717a;
    --toastry-close-hover-bg: #2a2a2a;
    --toastry-action-border: #3f3f46;
    --toastry-action-border-hover: #52525b;
    --toastry-spinner-track: #3f3f46;
  }
}

Playground