hcg-toast

A lightweight, zero-dependency JavaScript toast / notification library. Show success, error, warning, and info messages with auto-dismiss, sticky toasts, six screen positions, stack limits, pause on hover, optional progress bars, and custom icons.

• Zero dependencies, ~6 KB unminified
• UMD build - works with <script> tags, CommonJS, and bundlers
• Global API: toast() with shorthand helpers and toast.create() for custom instances
• Custom icons via icon, iconHtml, or hide with icon: false
• Accessible: role="alert" / role="status" with aria-live="off" on non-errors (avoids browser freezes during rapid bursts); errors use aria-live="assertive"
• TypeScript definitions included

Links

• Documentation & live demo: html-code-generator.com/javascript/toast-notification
• npm: npmjs.com/package/hcg-toast
• GitHub: github.com/html-code-generator/hcg-toast

Demo

Try the live demo and full documentation, or open index.html from the GitHub repo over a local server for a working example.

npx serve .

Installation

Install from npm:

npm install hcg-toast

Or download hcg-toast.js and hcg-toast.css and include them on your page:

<link rel="stylesheet" href="hcg-toast.css">
<script src="hcg-toast.js"></script>

In a module / Node environment:

require('hcg-toast/hcg-toast.css');
const toast = require('hcg-toast');

Or with ESM:

import toast from 'hcg-toast';
import 'hcg-toast/hcg-toast.css';

Usage

Singleton (default)

<link rel="stylesheet" href="hcg-toast.css">
<script src="hcg-toast.js"></script>
<script>
    toast.success('Changes saved!');
    toast.error('Upload failed', { title: 'Error', duration: 6000 });
    toast.dismiss(id);
    toast.dismissAll();
    toast.configure({ position: 'bottom-right', maxToasts: 5 });
</script>

Typed helpers

Shorthand methods set the toast type for you so you do not need to pass type on every call. Each helper uses the matching icon and accent color.

toast.success('Profile updated.');
toast.error('Could not save changes.');
toast.warning('You have unsaved edits.');
toast.info('Sync complete.');

// equivalent to toast(message, { type: 'success' })
toast('Saved!', { type: 'success', title: 'Done' });

Each call to show() (or a typed helper) returns a numeric toast id you can pass to dismiss(id).

Custom instance

const bottomToast = toast.create({
    position: 'bottom-center',
    maxToasts: 3,
});

bottomToast.info('Processing…', { duration: 0, closable: true });
bottomToast.dismissAll();
bottomToast.destroy();

Custom icons

By default each type shows a built-in icon (info, success, warning, error). Override per toast or set a default on the instance:

// Emoji or text icon
toast.success('Backup complete.', { icon: '💾' });

// SVG or HTML icon (trusted markup only)
toast.info('Syncing files…', {
  iconHtml: '<svg viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path d="M10 3a7 7 0 100 14A7 7 0 0010 3z"/></svg>'
});

// Hide the icon column
toast('Plain message.', { icon: false });

// Default icon for all toasts on an instance
const stars = toast.create({ icon: '⭐' });
stars.info('You have a new message.');

iconHtml takes precedence over icon when both are set. Only pass trusted HTML to iconHtml.

Options

| Option | Type | Default | Description | | ---------------- | ----------------------------------------- | ------------- | -------------------------------------------------------- | | message | string | required | Main body text | | title | string | - | Optional heading above the message | | type | 'info' \| 'success' \| 'warning' \| 'error' | 'info' | Toast variant (icon and accent color) | | duration | number | 4000 | Auto-dismiss delay in ms; 0 = sticky until dismissed | | closable | boolean | true | Show a close button | | pauseOnHover | boolean | true | Pause the auto-dismiss timer while hovered | | position | see below | 'top-right' | Screen position for this instance's container | | maxToasts | number | 5 | Max visible toasts; oldest dismissed when exceeded (per call or instance default) | | showProgress | boolean | true | Show a progress bar when duration > 0 | | icon | string \| false | type default | Custom icon text or emoji; false hides the icon | | iconHtml | string | - | Custom icon HTML (e.g. SVG); overrides icon | | ariaLive | 'off' \| 'polite' \| 'assertive' | 'off' | Live region on each toast; errors default to 'assertive' when unset | | onShow | (toast) => void | - | Called after the enter class is applied (animation start) | | onDismiss | (toast, reason) => void | - | Called when removed; reason: 'timeout', 'close', 'api' |

Positions: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right

Instance methods

| Method | Returns | Description | | --------------- | -------------- | ----------------------------------------------------- | | show(msg, opts) | number \| null | Show a toast; returns id | | success(msg, opts) | number \| null | Shorthand for type: 'success' | | error(msg, opts) | number \| null | Shorthand for type: 'error' | | warning(msg, opts) | number \| null | Shorthand for type: 'warning' | | info(msg, opts) | number \| null | Shorthand for type: 'info' | | dismiss(id) | void | Remove one toast with exit animation | | dismissAll() | void | Remove all toasts immediately | | configure(opts) | void | Merge default options for this instance | | destroy() | void | Dismiss all, remove container, detach instance |

The default singleton exposes the same methods on toast itself, plus toast.create(). Calling toast.destroy() removes the default instance so the next call recreates it.

Styling

All default styles live in hcg-toast.css, using plain single-class selectors and CSS custom properties on .hcg-toast-container. Edit that file directly, or override any rule from your own stylesheet (loaded after it). Available class hooks:

• .hcg-toast-container - fixed-position stack host (position modifiers: --top-right, --bottom-center, etc.)
• .hcg-toast-item - individual toast (type modifiers: --info, --success, --warning, --error)
• .hcg-toast-icon, .hcg-toast-body, .hcg-toast-title, .hcg-toast-message
• .hcg-toast-close - dismiss button
• .hcg-toast-progress-track / .hcg-toast-progress - auto-dismiss track and shrinking bar (shown when duration > 0 and showProgress: true)
• .hcg-toast-item--enter / .hcg-toast-item--exit - animation states

.hcg-toast-container {
    --hcg-toast-radius: 8px;
    --hcg-toast-success-accent: #10b981;
}

Multiple instances

Create as many toast containers as you need. Each call to toast.create() returns a fully independent instance with its own position, defaults, stack, and API. The shared hcg-toast.css styles them all, so you only link it once.

const topRight = toast.create({ position: 'top-right' });
const bottomCenter = toast.create({ position: 'bottom-center', maxToasts: 2 });

topRight.success('Saved!');
bottomCenter.info('Syncing…', { duration: 0 });

bottomCenter.destroy();

Notes when running several instances:

• Each instance injects its own .hcg-toast-container when first used.
• toast.configure() only affects the default singleton, not custom instances.
• Call each instance's destroy() when removing it permanently.

Browser support

Works in all modern browsers that support CSS transitions and requestAnimationFrame (Chrome, Firefox, Safari, Edge). Respects prefers-reduced-motion: reduce by disabling enter/exit and progress animations (the progress track stays visible for timed toasts).

License

MIT - HTML Code Generator (https://www.html-code-generator.com/)