NotifyX: JavaScript Toast Notifications with AI Streaming

Authorawalhadi

Last UpdateAugust 27, 2026

LicenseMIT

Features

Success, error, warning, info, loading, AI, and default toast types.
7 viewport positions across top, bottom, and center locations.
Stacked notifications with a configurable active-toast limit.
Promise notifications for loading, success, and error states.
AI metadata for model names, tool calls, token counts, and latency.
Streaming controller for progressive text updates.
5 animated presets plus a no-animation mode.
6 themes with automatic light and dark preference detection.
Swipe dismissal, action buttons, custom icons, titles, and callbacks.
ARIA roles, live regions, and labeled dismiss buttons.

Use Cases

Form submissions display success, error, and loading feedback after async requests.
AI chat tools display progressive status while streamed output arrives.
Dashboards show stacked system alerts when several events fire together.
Uploads report loading, completion, or failure from one Promise call.

How To Use It

Installation

Install the package from npm, pnpm, or Bun. Import the stylesheet at your application entry point before you create notifications.

# npm
npm install notifyx
# pnpm
pnpm add notifyx
# Bun
bun add notifyx

import NotifyX from 'notifyx';
import 'notifyx/style.css';
NotifyX.success('Settings saved.');

Browser Setup

Load the stylesheet before the JavaScript file when you use the package directly in an HTML page.

<link
  rel="stylesheet"
  href="https://unpkg.com/notifyx/dist/notifyx.min.css"
/>
<script src="https://unpkg.com/notifyx/dist/notifyx.min.js"></script>

Create Basic Toast Notifications

The four status helpers accept a message followed by an optional settings object. Each call returns the generated toast element.

NotifyX.success('Profile saved.');
NotifyX.error('Upload failed.');
NotifyX.warning('Storage is almost full.');
NotifyX.info('A new version is available.');

Position And Duration

NotifyX supports top-left, top-center, top-right, bottom-left, bottom-center, bottom-right, and center positions. The default duration is 3000 milliseconds. Set duration to 0 for a persistent toast.

NotifyX.info('Sync started.', {
  position: 'bottom-center',
  duration: 5000
});
NotifyX.error('Connection lost.', {
  position: 'top-center',
  duration: 0
});

Promise Notifications

NotifyX.promise() follows one asynchronous task through loading, success, and error states. The loading value accepts a string or an object with a title and message. Success and error values accept strings, callbacks, or message objects.

NotifyX.promise(fetch('/api/account'), {
  loading: 'Loading account...',
  success: 'Account loaded.',
  error: 'Account request failed.',
  position: 'bottom-right'
});

AI Metadata

NotifyX.ai() renders an AI toast and accepts metadata for a model, MCP-style tool name, confidence value, token count, latency, and streaming state.

NotifyX.ai('Checking repository files...', {
  ai: {
    model: 'assistant-model',
    toolName: 'read_file',
    tokens: 420,
    latencyMs: 760
  }
});

Streaming Text

NotifyX accepts one StreamOptions object. The returned controller appends chunks with update(), replaces the full message with set(), and finishes with success or error state methods.

const stream = NotifyX.stream({
  title: 'Code Review',
  loadingMessage: 'Reviewing files...',
  position: 'bottom-right',
  ai: {
    model: 'assistant-model',
    streaming: true
  },
  onChunk: (chunk, fullText) => {
    console.log(fullText);
  }
});
stream.update('Checking imports. ');
stream.update('Reviewing event handlers. ');
stream.update('Scanning error states.');
stream.success('Review complete.', {
  ai: {
    model: 'assistant-model',
    streaming: false,
    latencyMs: 920
  }
});

Action Buttons and Custom Content

actions accepts buttons with primary, ghost, or danger variants. The richHtml value reaches the message element through innerHTML. Sanitize any untrusted value before passing it to NotifyX.

NotifyX.show({
  message: 'Your draft has unsaved edits.',
  title: 'Unsaved Changes',
  type: 'warning',
  duration: 0,
  actions: [
    {
      label: 'Save',
      variant: 'primary',
      onClick: (toastId) => saveDraft(toastId)
    },
    {
      label: 'Discard',
      variant: 'danger',
      onClick: (toastId) => discardDraft(toastId)
    }
  ]
});

Global Configuration

NotifyX.configure() stores defaults for later notifications. Per-toast settings take precedence when a call includes the same option.

NotifyX.configure({
  position: 'top-right',
  duration: 4000,
  maxToasts: 3,
  animation: 'spring',
  theme: 'auto',
  pauseOnHover: true
});

Themes

The library currently includes 6 theme presets. auto follows the operating system color preference, while the other values force a specific style. You can use the setTheme() method to change the global theme at runtime.

auto follows the system light or dark preference.
light uses the light theme.
dark uses the dark theme.
glass uses the frosted glass theme.
minimal uses the minimal theme.
brutal uses the brutalist theme.

NotifyX.setTheme('glass');
NotifyX.success('Invoice exported.', {
  theme: 'minimal'
});

Animations

The animation option accepts spring, slide, bloom, flip, fade, or none. The default preset is spring.

NotifyX.info('Background sync finished.', {
  animation: 'bloom'
});

Configuration & API Reference

Configuration Options

NotifyX.show() accepts the full ToastOptions object. The status helpers accept the same settings except for the required message field, which comes from their first argument.

message (string): Required message text for show().
title (string): Optional title above the message.
type (success | error | warning | info | loading | ai | default): Toast type. Default is info.
position (Position): Screen location. Default is top-right.
duration (number): Display time in milliseconds. Default is 3000. A value of 0 keeps the toast open.
dismissible (boolean): Controls the close button. Default is true.
animation (spring | slide | bloom | flip | fade | none): Animation preset. Default is spring.
theme (auto | light | dark | glass | minimal | brutal): Theme preset. Default is auto.
priority (low | normal | high | critical): Priority metadata. Default is normal. In 4.0.1, critical switches the live region to assertive and applies the critical visual treatment.
id (string): Custom toast ID for updates and dismissal.
actions (ToastAction[]): Action buttons displayed with the message.
icon (string | HTMLElement): Custom icon value. For an initial 4.0.1 toast, use a string or emoji. The initial renderer does not append an HTMLElement value as a DOM node.
richHtml (string): HTML message content. Sanitize untrusted values before use.
ai (AIMetadata): AI model, tool, confidence, streaming, token, and latency metadata.
pauseOnHover (boolean): Pauses the dismiss timer during pointer hover. Default is true.
pauseOnFocus (boolean): Declared focus-pause flag. Default is false. NotifyX 4.0.1 does not bind a window focus or visibility listener for this option.
onClose ((id) => void): Runs after timed dismissal or the built-in close button removes the toast. Programmatic dismiss() and clear() do not retain this callback in 4.0.1.
onClick ((id) => void): Runs after the main toast area receives a click.
maxToasts (number): Maximum active toasts for a position. Default is 5.
showProgress (boolean): Shows the timed progress bar when enabled.
showIcon (boolean): Shows the toast icon when enabled.
className (string): Appends a custom CSS class to the toast element.

Action Options

label (string): Button label.
onClick ((toastId) => void): Runs when the action button receives a click.
variant (primary | ghost | danger): Optional action style.

AI Metadata Options

model (string): Model or agent name shown with the toast.
toolName (string): Tool name shown in the metadata area.
confidence (number): Confidence value from 0 to 1.
streaming (boolean): Marks the notification as an active streaming update.
tokens (number): Token count shown in the metadata area.
latencyMs (number): Response latency in milliseconds.

AI Helper Options

NotifyX.ai() also accepts three shorthand fields that map into AI metadata.

agentName (string): Maps the value to the displayed model name.
confidence (number): Maps the value to AI confidence metadata.
showCursor (boolean): Marks the AI toast as a streaming update when set to true.

Promise Options

loading (string | object): Loading message or an object with title and message.
success (string | function | object): Success text, result callback, or message object. The 4.0.1 transition reads the object message and does not apply its optional title.
error (string | function | object): Error text, error callback, or message object. The 4.0.1 transition reads the object message and does not apply its optional title.
position (Position): Toast position for the Promise lifecycle.
animation (AnimationPreset): Animation preset for state changes.
id (string): Custom ID shared across the Promise states.

Stream Options

position (Position): Streaming toast position.
animation (AnimationPreset): Animation preset.
id (string): Custom stream toast ID.
title (string): Optional title.
ai (AIMetadata): AI metadata shown with the stream.
onComplete ((finalMessage) => void): Runs when stream.success() finalizes the stream and receives the accumulated streamed text.
onChunk ((chunk, accumulated) => void): Runs after each appended chunk.
loadingMessage (string): Initial text shown before streamed chunks arrive.

API Methods

// Create a fully configured toast and return its HTMLElement.
const toastElement = NotifyX.show(options);
// Create typed status toasts and return each HTMLElement.
NotifyX.success(message, options);
NotifyX.error(message, options);
NotifyX.warning(message, options);
NotifyX.info(message, options);
// Create an AI toast with optional AI metadata.
NotifyX.ai(message, options);
// Show and dismiss the centered loading state.
NotifyX.loading(message, options);
NotifyX.dismissLoading();
// Follow a Promise through loading, success, and error states.
const result = NotifyX.promise(promiseOrFunction, promiseOptions);
// Create a progressive text stream and return its controller.
const streamController = NotifyX.stream(streamOptions);
// Update an active toast by ID.
NotifyX.update(toastId, options);
// Pause or resume active dismiss timers.
NotifyX.pauseAll();
NotifyX.resumeAll();
// Create several toasts and return their generated IDs.
const toastIds = NotifyX.batch(toastOptionsArray, sharedOptions);
// Change the global theme or global defaults.
NotifyX.setTheme('dark');
NotifyX.configure(defaultOptions);
// Dismiss one toast or clear every active toast.
NotifyX.dismiss(toastIdOrElement);
NotifyX.clear();

Static Properties

The class exposes the current position, animation, theme, and default-option constants for code that needs the library’s predefined values.

NotifyX.POSITIONS;
NotifyX.ANIMATION_PRESETS;
NotifyX.THEMES;
NotifyX.DEFAULT_OPTIONS;

Advanced Accessors

Three getters expose the internal queue, animation engine, and stream bridge for advanced integrations.

NotifyX.queue;
NotifyX.animation;
NotifyX.stream_bridge;

TypeScript Exports

The package exports the public types used by the static API and configuration objects.

import type {
  ToastType,
  Position,
  AnimationPreset,
  ToastPriority,
  ThemePreset,
  ToastAction,
  ToastOptions,
  PromiseOptions,
  StreamOptions,
  StreamController,
  AIMetadata
} from 'notifyx';

Alternatives

Changelog

v4.1.1 (08/27/2026)

Fixed the brutal theme icon border and border-radius styling.

v4.0.0 (04/24/2026)

Introduced AI and LLM streaming notifications.
Introduced stacked toast rendering and priority metadata.
Introduced Web Animations API presets.
Introduced Promise-driven notification states.
Introduced AI metadata for model, tool, token, and latency information.
Introduced swipe dismissal for touch interactions.
Moved styling to dependency-free vanilla CSS.
Updated the static notification API and UMD build.