Stackable JavaScript Toast Notifications with Sound and Actions – chyrp

chyrp is a Vanilla JavaScript toast notification library that enables a notification to change from a loading message to a completion alert in place and supports action buttons for user responses.

Features

• Info, warning, error, and loading notification styles.
• Automatic stacking with an overflow counter for additional messages.
• 6 position options and bottom-centered placement on small screens.
• Timed dismissal with pause on hover or keyboard focus.
• Pointer-based swipe dismissal and click-to-dismiss behavior.
• Configurable suppression of duplicate notifications.
• Promise tracking with loading, completion, and error states.
• Built-in sound presets and custom audio options.
• Automatic light and dark colors with CSS variable overrides.
• Reduced-motion preferences and TypeScript definitions.

How To Use It

Basic Usage

Place the stylesheet in the document head and the script at the end of the body. chyrp needs document.body to exist when it creates a notification.

<!-- In <head> -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/chyrp/dist/style.css">
<!-- Before </body> -->
<script src="https://unpkg.com/chyrp/dist/index.iife.js"></script>
<script>
  Chyrp.chyrp.info('Your settings were saved.');
</script>

Or install the package and import the required CSS once in your app entry file.

npm install chyrp

import { chyrp } from 'chyrp';
import 'chyrp/style.css';
chyrp.info('Your settings were saved.');
chyrp.warning('Storage is running low.');
chyrp.error('Unable to upload the file.');

Notifications with Actions

Action buttons can handle an Undo request or another explicit operation. The example expects an application-defined restoreFile() function. The toast closes after a button click unless its onClick handler returns false.

chyrp does not wait for a promise returned from this handler, so use return false and dismiss or update the toast yourself after asynchronous work.

chyrp({
  title: 'File deleted',
  body: 'report.pdf was moved to the trash.',
  persistent: true,
  actions: [
    {
      label: 'Undo',
      style: 'primary',
      onClick: () => restoreFile()
    },
    { label: 'Dismiss' }
  ]
});

Track an Asynchronous Task

Pass an existing promise to chyrp.promise() to show loading feedback and update the notification after resolution or rejection.

The example expects an application-defined saveSettings() function that returns a promise. The success handler receives the resolved value, and error receives the rejection reason.

chyrp.promise(saveSettings(), {
  loading: 'Saving settings...',
  success: () => 'Settings saved.',
  error: (error) => ({
    title: 'Save failed',
    body: error instanceof Error ? error.message : String(error)
  })
});

A loading toast displays a spinner by default. A positive max changes that indicator to a progress donut.

const progressToast = chyrp.loading('Preparing your export...', {
  max: 100,
  value: 0
});
progressToast.update({ value: 65, body: 'Exporting: 65%' });
progressToast.update({
  style: 'info',
  body: 'Your export is ready.',
  timeout: 2500
});

Configure Position, Timing, and Sound

Sound is enabled by default. configure() can change the global position, hover behavior, sound, and replay settings.

import { chyrp, configure } from 'chyrp';
configure({
  position: 'bottom-right',
  pauseOnHover: true,
  sound: false,
  resound: false
});
chyrp.info('Preferences updated.', {
  position: 'top-center',
  timeout: 6000,
  sound: 'success'
});

Update and Dismiss Notifications

Each call that creates a toast returns a ToastHandle with update() and dismiss(). You can change the message, notification style, action buttons, and timer through that handle.

const statusToast = chyrp.loading('Synchronizing data...', {
  sound: false
});
setTimeout(() => {
  statusToast.update({
    style: 'info',
    body: 'Synchronization complete.',
    timeout: 2500
  });
}, 1200);

channel groups notifications for dismissal. dismissChannel(name) clears that group, and dismissAll() clears every active toast.

import { chyrp, dismissChannel, dismissAll } from 'chyrp';
chyrp.warning('Connection interrupted.', {
  channel: 'network',
  persistent: true
});
// Later, after the connection recovers:
// dismissChannel('network');
// To clear all live notifications:
// dismissAll();

API Methods

A ToastHandle returned by a creation method has two methods.

Full Toast Options

Global Configuration

configure(options) accepts only the global fields below. Per-toast options have priority over their corresponding global settings.

Action, Promise, and Sound Types

Each object in the actions array accepts three public fields. Action callbacks receive the toast handle as their argument.

PromiseOptions<T, E> has three optional branches. Each accepts PromiseValueSpec, which is a string, a ToastOptions object, or a function returning either. If the relevant success or error branch is omitted, the notification dismisses when the promise settles.

SoundOption accepts a boolean, a built-in sound preset, an audio URL string, or ChimeNote[]. The presets gentle, alert, success, and error use the Web Audio API. configure({ soundPresets }) accepts a partial object with those four preset keys, each assigned an array of notes. Custom notes have the following fields.

Styling and CSS Variables

chyrp follows prefers-color-scheme for its default light and dark colors. Apply class="dark" to <html> to force dark colors or class="light" to use the light palette.

Set the --tt-* custom properties in your CSS after the library stylesheet. For explicit dark colors, define the overrides in html.dark too, since the built-in dark-mode rules can supersede :root values.

-root {
  --tt-bg: #fff;
  --tt-title-color: #1e293b;
  --tt-body-color: #475569;
  --tt-info: #2563eb;
}
html.dark {
  --tt-bg: #111827;
  --tt-title-color: #f9fafb;
  --tt-body-color: #d1d5db;
}

The default stylesheet exposes 25 CSS custom properties. These are their light-mode values.

UI and Text

Notification Accents and Buttons

Loading, Progress, and Overflow

Optional Native Alert Replacement

interceptAlert() replaces window.alert() with info-style toast messages until its returned restore function is called. The override is opt-in. Native window.confirm() and window.prompt() are unaffected.

import { interceptAlert } from 'chyrp';
const restoreAlert = interceptAlert();
window.alert('Operation completed.');
// Restore the native browser dialog.
restoreAlert();

Alternatives & Related Resources

• Sonner-Style Toasts in Vanilla JavaScript – vanilla-sonner
• Modern Toast Popup JavaScript Library – EggyJS
• Material Design Toast & Snackbar Library with Action Buttons – MiniSnackbar
• Vanilla JS Info/Warning/Error/Danger Toast Notification Library – Toasteur.js