JavaScript Toast Notification Library with Actions and HTML - rm-toast-notification

Authormalikrajat

Last UpdateAugust 20, 2026

LicenseMIT

Features:

Four notification states for success, error, warning, and info.
Four corner positions with animated entry effects.
Configurable auto-dismiss timers with hover pause.
Persistent messages for long-lived notices and actions.
Action buttons and toast-level click callbacks.
DOMPurify sanitization for HTML message content.
Custom background colors and optional logo images.
Programmatic closing, clearing, and container cleanup.

Use Cases:

Report save, validation, and server states after form submissions.
Keep failed uploads visible with a Retry action.
Attach Undo or View actions to dashboard status messages.
Show longer session notices with hover-paused dismissal timers.

How To Use It:

Installation

Install and import it via NPM

npm install @codewithrajat/rm-toast-notification

You can also import the ESM build from CDN directly into your document:

<script type="module">
  import ToastNotification from 'https://esm.sh/@codewithrajat/[email protected]/es2022/index.mjs';
  const notifications = new ToastNotification();
  notifications.showToast({
    type: 'info',
    body: 'Your profile settings are ready.',
    duration: 3200
  });
</script>

Basic Usage

Create a ToastNotification instance and reuse it for subsequent messages. The duration value controls the auto-dismiss delay in milliseconds.

import ToastNotification from '@codewithrajat/rm-toast-notification';
const notifications = new ToastNotification();
notifications.showToast({
  type: 'success',
  header: 'Changes saved',
  body: 'Your account preferences have been updated.',
  position: 'top-right',
  duration: 3500
});

Create a Persistent Toast with an Action

Set duration to 0 for a message that stays on screen until dismissal. The action button uses its own click handler and does not trigger the toast-level callback.

notifications.showToast({
  type: 'error',
  header: 'Connection lost',
  body: 'The latest changes have not reached the server.',
  duration: 0,
  actionButton: {
    text: 'Retry',
    onClick: function () {
      reconnect();
    }
  }
});

Display HTML in the Message Body

The body option accepts HTML and passes it through DOMPurify before DOM insertion. The sanitizer removes style, class, ID, event-handler, and data attributes along with elements such as script, style, iframe, object, embed, and form.

notifications.showToast({
  type: 'warning',
  header: 'Storage almost full',
  body: '<strong>92% used.</strong> Remove old uploads to free space.',
  duration: 6000
});

Add a Toast Click Handler

The optional onClick callback runs when the main toast area is clicked. Close-button and action-button clicks are excluded. The toast closes after the callback runs.

notifications.showToast({
  type: 'info',
  body: 'A new report is available.',
  onClick: function () {
    window.location.href = '/reports/latest';
  }
});

Control Toasts Programmatically

showToast() returns the generated HTMLDivElement. Pass that element to closeToast() when an asynchronous task should remove a specific persistent message.

const pendingToast = notifications.showToast({
  type: 'info',
  body: 'Processing your export...',
  duration: 0
});
finishExport().then(function () {
  if (pendingToast) {
    notifications.closeToast(pendingToast);
  }
});

All Configuration Options

type ('success' | 'error' | 'warning' | 'info'): Sets the notification state and default color. Default: info.
position ('top-left' | 'top-right' | 'bottom-left' | 'bottom-right'): Places the toast container in a screen corner. Default: top-right.
duration (number): Sets the dismissal delay in milliseconds. Default: 3000. Zero or a negative number creates a persistent toast.
header (string): Adds plain text above the message body.
body (string): Adds plain text or sanitized HTML content.
footer (string): Adds plain text below the main content.
logo (string): Adds a 30 by 30 pixel image from an accepted URL.
color (string): Sets the background with supported hex, rgb(), or rgba() values.
onClick (function): Runs after a click on the main toast area.
actionButton (object): Adds a button with text and onClick properties.
animation (boolean): Controls the slide-in animation. Default: true.

API Methods

// Create a toast and return its HTMLDivElement.
const element = notifications.showToast({
  type: 'success',
  body: 'Export finished.'
});
// Check whether a string contains HTML elements.
const containsHtml = notifications.isItHtml('<strong>Finished</strong>');
// Close one generated toast.
if (element) {
  notifications.closeToast(element);
}
// Close every active toast.
notifications.clearAll();
// Clear active toasts and remove the shared container.
notifications.destroy();
// Return the default background color for a notification type.
const successColor = notifications.getColor('success');
// Return the built-in slide animation for a position.
const animation = notifications.getAnimation('bottom-right');
// Return the default action button color for a notification type.
const buttonColor = notifications.getActionButtonColor('warning');

JavaScript Toast Notification Library with Actions and HTML – rm-toast-notification