🍞 Toaster v2.0

A lightweight, customizable toast notification library for the web.
Inline styles · Themes · Promise API · Swipe to dismiss

✨ Try it now

📦 Installation

Simply include the https://toastor.nirajkumarsharma.com.np/toaster.js file in your HTML. The library exposes a global toast object and the Toaster class for custom instances.

<script src="https://toastor.nirajkumarsharma.com.np/toaster.js" defer></script>

You can also install via npm (coming soon) or use a CDN.

🚀 Quick Start

// Basic usage
toast('Hello World!');

// Success variant
toast.success('Profile updated!');

// With options
toast.error('An error occurred', {
  title: 'Error',
  description: 'Please try again later.',
  duration: 5000
});

✨ Features

🎯 Multiple Positions

Top left/center/right, bottom left/center/right.

🎨 Fully Customizable

CSS variables, inline styles, or theme objects.

⏱️ Progress Bar

Visual countdown that pauses on hover.

👆 Swipe to Dismiss

Works with touch and mouse.

🤞 Promise API

Automatically handle async operations.

📱 Responsive

Looks great on all screen sizes.

⚙️ Instance Configuration

Create a custom toaster with new Toaster(options).

const myToaster = new Toaster({
  position: 'bottom-center',  // default position
  duration: 5000,             // default auto-dismiss time
  maxToasts: 3,               // max toasts shown at once
  gap: 16,                    // space between toasts
  reverseOrder: true,         // new toasts appear at bottom
  swipeToDismiss: true,       // enable swipe to dismiss
  pauseOnHover: true,         // pause timer on hover
  theme: 'dark'               // 'light', 'dark', 'auto', or object
});

All Configuration Options

Option	Type	Default	Description
position	string	'top-right'	Where toasts appear. Valid: 'top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'
duration	number	4000	Time in ms before auto-dismiss. Set to `0` to disable.
maxToasts	number	5	Maximum number of toasts visible at once per position.
gap	number	12	Space (px) between stacked toasts.
reverseOrder	boolean	false	If `true`, new toasts appear at the bottom of the stack (useful for bottom positions).
swipeToDismiss	boolean	true	Allow swiping/dragging to dismiss toasts.
pauseOnHover	boolean	true	Pause auto-dismiss timer when hovering over a toast.
theme	string \| object	'auto'	Predefined theme ('light', 'dark') or an object mapping CSS variables to values.

📖 Complete Method Reference

All methods return a unique toast id (string) that can be used to dismiss or update the toast later.

Method	Description
`toast(message, options?)`	Show a plain toast (no icon).
`toast.success(message, options?)`	Show a success toast with a green check icon.
`toast.error(message, options?)`	Show an error toast with a red X icon.
`toast.info(message, options?)`	Show an info toast with a blue "i" icon.
`toast.loading(message, options?)`	Show a loading toast with a spinner. Default `duration: 0` (never auto-dismiss).
`toast.custom(message, options?)`	Show a custom toast where you provide the icon via `icon` option.
`toast.promise(promise, messages, options?)`	Automatically show loading, then success/error based on promise resolution.
`toast.dismiss(id?)`	Dismiss a specific toast by its id. If called without an id, dismisses all toasts.
`toast.dismissAll(position?)`	Dismiss all toasts. Optionally provide a position string to dismiss only toasts from that container.

📋 Toast Options (per call)

Each method accepts an optional options object to customize that specific toast.

Option	Type	Description
title	string	Bold title displayed above the main message.
description	string	Smaller, secondary text with reduced opacity.
duration	number	Override the default display duration (in ms).
position	string	Override the container position for this toast only.
icon	string (SVG)	Custom icon HTML. Only applicable for `custom` type.
id	string	Custom identifier. Useful for programmatic dismissal or updates.
style	object	Inline CSS styles to apply directly to the toast element (e.g., `{ border: '2px solid red' }`).

🧪 Live Examples

Basic Variants

toast('Plain message');
toast.success('Success!');
toast.error('Error!');
toast.info('Info');
toast.loading('Loading...');

With Title & Description

toast.success('Changes saved', {
  title: 'Profile Updated',
  description: 'Your data has been saved successfully.'
});

Position Variations (Fixed!)

toast('Top Left', { position: 'top-left' });
toast('Bottom Center', { position: 'bottom-center' });

Custom Duration & Persistent

Inline Styles

toast('Custom style', {
  style: {
    border: '2px solid #713200',
    padding: '16px',
    color: '#713200',
    background: '#fff5e6',
    fontWeight: 'bold'
  }
});

Promise API

toast.promise(fetchData, {
  loading: 'Loading...',
  success: (data) => `Loaded ${data.length} items`,
  error: (err) => `Failed: ${err.message}`
});

Custom Icon

const myIcon = `<svg ...>...</svg>`;
toast.custom('Custom notification', { icon: myIcon, title: 'Reminder' });

Programmatic Dismissal

const id = toast.loading('Processing...');
setTimeout(() => toast.dismiss(id), 2000);
toast.dismissAll(); // dismiss all
toast.dismissAll('bottom-center'); // dismiss only from bottom-center

Multiple Instances

const topLeft = new Toaster({ position: 'top-left', theme: 'dark' });
const bottomRight = new Toaster({ position: 'bottom-right' });
topLeft.info('Message from top-left');
bottomRight.success('Message from bottom-right');

🎨 Styling & Customization

Override CSS variables or pass a theme object.You have three ways to customize the appearance:

CSS Variables – Override in your own stylesheet.
Theme Object – Pass a theme when creating an instance.
Inline Styles – Pass a style object per toast.

1. CSS Variables

Define these variables in your CSS (after loading the library):

:root {
  --toast-bg: #ffffff;
  --toast-text: #111;
  --toast-success: #059669;
  --toast-error: #dc2626;
  --toast-info: #2563eb;
  --toast-loading: #7c3aed;
  --toast-border-radius: 24px;
  --toast-gutter: 16px;
}

2. Theme Object

const customToaster = new Toaster({
  theme: {
    '--toast-bg': '#1e1e2f',
    '--toast-text': '#f0f0f0',
    '--toast-success': '#2ecc71',
    '--toast-border-radius': '30px'
  }
});

3. Inline Styles

toast('Custom border', {
  style: {
    border: '2px solid #713200',
    padding: '16px',
    color: '#713200',
    background: '#fff5e6',
    fontWeight: 'bold'
  }
});

🌓 Dark Mode & Accessibility

The library automatically adapts to the system dark mode preference. It also respects prefers-reduced-motion and provides proper ARIA attributes.

💡 Pro Tip: You can disable animations for all toasts by setting the CSS variable --toast-animation: none or using the reduced motion media query.