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)
});

Options Object

Passed as the second argument to any toast method.

toast('File deleted', {
  description: 'The file has been moved to trash.',
  duration: 6000,
  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