Modern JavaScript Toast Notification & Modal Popup Library - JSPT

Authorlevkris

Last UpdateFebruary 17, 2026

LicenseMIT

Features:

Promise-based icon loading: You can chain toast or popup calls only after the icon fonts have fully loaded.
Persistent toasts: Setting duration: -1 keeps a toast on screen indefinitely. It can then be dismissed on click via close_on_click: true.
HTML content: Popups support a content_type: "html" mode that accepts arbitrary HTML strings.
Icon flexibility: Left and right icons on toasts support Google Material Symbols (rounded and outlined), Lucide icons, raw SVG, image URLs, emoji, and plain text.
Mobile-responsive: Works perfectly on mobile and desktop.
Customizable Styling: You can easily override animations and themes in your own stylesheet.

How To Use It:

1. Download and import JSPT into your document.

<!-- If you use icons, include the font manually -->
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded">

<!-- Browser -->
<link rel="stylesheet" href="/dist/jspt/jspt.css">
<script src="/dist/jspt/jspt.js"></script>

// ES Module
# NPM
$ npm install @wokki20/jspt

import { makeToast, makePopup } from './dist/jspt.module.js';

2. When you include JSPT via a classic <script> tag, call jspt.importScript() before using any icon-dependent options. This method dynamically loads the requested fonts and scripts, then returns a promise.

Available library names for importScript():

'material_symbols_rounded' — Google Material Symbols (Rounded variant)
'material_symbols_outlined' — Google Material Symbols (Outlined variant)
'lucide' — Lucide Icons
'highlightjs' — Highlight.js, for code syntax highlighting inside popups

jspt.importScript({
  // Load the Google Material Symbols (Rounded) icon font
  names: ['material_symbols_rounded']
}).then(() => {
  // Icons are now available — safe to render toasts with icon options
  console.log('Icon libraries loaded.');
}).catch(error => {
  // Handle load failures gracefully
  console.error('Failed to load icon libraries:', error);
});

3. Create toast messages with the ‘makeToast’ method.

Full Options:

message (string): The text content displayed inside the toast. Required.
style (string): Visual style of the toast. Accepts 'default' or 'default-error'. Defaults to 'default'.
custom_id (string): An optional identifier for the toast. If a toast with this ID already exists, it gets replaced in-place.
icon_left (string): The icon name or content to render on the left side of the toast.
icon_left_type (string): The icon system for the left icon. Defaults to 'google_material_rounded'.
icon_left_action (function): A callback fired when the left icon is clicked.
icon_right (string): The icon name or content to render on the right side of the toast.
icon_right_type (string): The icon system for the right icon. Defaults to 'google_material_rounded'.
icon_right_action (function): A callback fired when the right icon is clicked.
duration (number): Time in milliseconds before the toast auto-dismisses. Set to -1 for a persistent toast. Defaults to 5000.
close_on_click (boolean): When true, clicking anywhere on the toast dismisses it. Defaults to false.
onclick (function): A callback fired when the body of the toast is clicked.

Supported icon types:

'google_material_rounded' — Google Material Symbols (Rounded)
'google_material_outlined' — Google Material Symbols (Outlined)
'svg' — Raw SVG markup string
'image' — An image URL
'text' — Plain text string
'emoji' — An emoji character
'lucide_icon' — Lucide icon name

// Minimal usage — only message is required
jspt.makeToast({
  message: "Your changes have been saved."
});
// Toast with Icon and Custom Duration
jspt.importScript({ names: ['material_symbols_rounded'] }).then(() => {
  jspt.makeToast({
    message: "File uploaded successfully.",
    style: "default",               // 'default' or 'default-error'
    icon_left: "check_circle",      // Icon name from the loaded font
    icon_left_type: "google_material_rounded",
    duration: 3000                  // Auto-dismiss after 3 seconds
  });
});
// Error Toast (Persistent)
jspt.makeToast({
  style: "default-error",           // Red/error visual style
  message: "Authentication failed. Please try again.",
  icon_left: "error",
  icon_left_type: "google_material_rounded",
  duration: -1,                     // Keep on screen indefinitely
  close_on_click: true              // User dismisses by clicking the toast
});
// Toast with Clickable Right Icon
jspt.makeToast({
  message: "New message received.",
  icon_right: "open_in_new",
  icon_right_type: "google_material_rounded",
  icon_right_action: () => {
    // Fires when the right icon is clicked
    window.location.href = '/messages';
  },
  duration: 5000
});
// Replaceable Toast via Custom ID
// Calling makeToast with the same custom_id replaces the existing toast
jspt.makeToast({
  custom_id: "upload-status",
  message: "Uploading… 45%",
  duration: -1
});
// Later in your upload handler:
jspt.makeToast({
  custom_id: "upload-status", // Replaces the previous toast in-place
  message: "Upload complete.",
  style: "default",
  duration: 3000
});

4. Create modal popups with the ‘makePopup’ method.

Full Options:

content_type (string): Sets the content rendering mode. Accepts 'text' or 'html'. Defaults to 'text'.
style (string): Visual style of the popup. Defaults to 'default'.
header (string): Text displayed in the popup header bar.
title (string): A title line within the popup body. Available in text mode only.
message (string): The body text of the popup. Available in text mode only.
content (string): An HTML string rendered inside the popup. Available in html mode only.
close_on_blur (boolean): When true, clicking outside the popup closes it. Defaults to true.
custom_id (string): An identifier for the popup. Defaults to a randomly generated string. Required if you intend to close the popup with jspt.closePopup().

// Text Popup
jspt.makePopup({
  content_type: "text",             // Plain text mode
  header: "Account Notice",        // Appears at the top of the popup
  title: "Your session will expire soon",
  message: "Save your work to avoid losing unsaved changes.",
  close_on_blur: true              // Closes when user clicks outside the popup
});
// HTML Popup
jspt.makePopup({
  content_type: "html",            // Full HTML mode — accepts any markup
  header: "Quick Setup",
  content: `
    <h2>Configure your preferences</h2>
    <p>Select a theme and click Save.</p>
    <button onclick="savePrefs()">Save</button>
  `,
  close_on_blur: false,            // Prevent accidental dismissal
  custom_id: "setup-popup"         // Assign an ID so it can be closed programmatically
});
// Closing a Popup Programmatically
// Closes the popup that was opened with custom_id: "setup-popup"
jspt.closePopup({
  custom_id: "setup-popup"
});

FAQs:

Q: Do I need to call importScript() every time I show a toast?
A: No. Call it once when your page loads (or before your first icon-dependent notification), then call makeToast() freely after the promise resolves.

Q: Why aren’t my icons appearing when I use the ES module build?
A: The ES module build does not call importScript() . This method is only available on the jspt global in the classic script build. When you import from jspt.module.js, include icon font stylesheets manually as <link> tags in your HTML.

Q: Can I display a popup and immediately close it from code?
A: Yes. Pass a custom_id when calling makePopup(), then call jspt.closePopup({ custom_id: 'your-id' }) at any point afterward. This is useful for auto-dismissing onboarding popups after a timed delay.