Elegant Notice Bar With Progress Bar – notice.js

notice.js is a dependency-free JavaScript toast notification library for stackable status messages with optional countdown progress bars.

It ships as browser, ESM, and CommonJS builds with TypeScript definitions, and the API works through direct status helpers or configurable NoticeJs instances.

Features

• Success, info, warning, and error notification types.
• 11 screen positions, including full-width top and bottom bars.
• Timed or persistent notices with optional countdown progress bars.
• Automatic timer pausing on hover, keyboard focus, and hidden browser tabs.
• Configurable button, click, and touch or pen swipe dismissal, plus Escape from a focused notice.
• Promise notices for loading, success, and error states.
• Action buttons with optional custom handlers.
• Programmatic updating, closing, pausing, resuming, and deduplication by ID.
• Configurable notice limits per position.
• Modal notices, RTL layout, and custom open or close animation classes.
• Plain-text rendering by default with opt-in HTML and a custom sanitizer hook.
• ARIA live regions, modal focus handling, and reduced-motion behavior.
• Theme customization through CSS custom properties.

How to use it

Direct browser setup

Load the stylesheet before the browser build:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/notice.js@1/dist/noticejs.css">
<script src="https://cdn.jsdelivr.net/npm/notice.js@1/dist/notice.js"></script>

Use one of the static helpers for a basic toast:

NoticeJs.success('Profile saved');

Create an instance when the notice needs custom content or behavior:

const notice = new NoticeJs({
  title: 'Saved',
  text: 'Your changes are live.',
  type: 'success',
  position: 'topRight',
  timeout: 5000
}).show();

npm and ESM

npm install notice.js

import { NoticeJs } from 'notice.js';
import 'notice.js/noticejs.css';
NoticeJs.info('New version available');

Notification types

The four built-in type values are success, info, warning, and error. Static helpers are available for each type:

NoticeJs.success('Saved');
NoticeJs.info('New message');
NoticeJs.warning('Storage is almost full');
NoticeJs.error('Upload failed', { title: 'Error' });

Promise notifications

NoticeJs.promise() creates a loading notice and updates it when the promise resolves or rejects. It returns the original promise.

const profilePromise = NoticeJs.promise(saveProfile(), {
  loading: 'Saving profile...',
  success: 'Profile saved',
  error: (error) => ({
    title: 'Save failed',
    text: error.message
  })
});

Action buttons

new NoticeJs({
  text: 'Email archived',
  actions: [
    {
      label: 'Undo',
      onClick: () => restoreEmail()
    },
    {
      label: 'Details',
      onClick: () => openDetails(),
      closeOnClick: false
    }
  ]
}).show();

Action fields

Update, close, and deduplicate notices

Use a stable id to update an existing notice and avoid duplicate stacking.

const uploadNotice = new NoticeJs({
  id: 'upload-status',
  text: 'Uploading...',
  timeout: false,
  loading: true
}).show();
uploadNotice.update({
  text: 'Upload complete',
  type: 'success',
  loading: false,
  timeout: 3000
});
uploadNotice.close();
NoticeJs.get('upload-status')?.close();
NoticeJs.closeAll();
NoticeJs.closeAll('bottomRight');

Global defaults

NoticeJs.overrideDefaults({
  position: 'bottomRight',
  timeout: 5000
});
NoticeJs.resetDefaults();

Configuration options

new NoticeJs(options?) accepts one optional NoticeOptions object. Omitted values use the current global defaults.

Content and type

Timing and dismissal

Position, layout, and stacking

Actions, accessibility, and callbacks

Available positions

top and bottom create full-width bars and display one notice at a time.

Instance API

position and modal cannot change after a notice has been shown. Set those options before show().

Static API

NoticeJs.promise() parameters

input accepts a promise or a function that returns a promise. options accepts the regular notice options used for the loading notice.

Callbacks

Each callback receives the notice instance as its first argument and as this.

new NoticeJs({
  text: 'Hello',
  callbacks: {
    afterClose: (notice) => {
      console.log(`${notice.id} closed`);
    }
  }
}).show();

Theme customization

Set the library’s CSS custom properties on :root to change the default theme:

:root {
  --noticejs-success-bg: #0f766e;
  --noticejs-success-accent: #115e59;
  --noticejs-radius: 12px;
  --noticejs-width: 360px;
  --noticejs-font-family: Inter, sans-serif;
}

Layout and shared theme variables

Status and modal theme variables

Upgrading from 0.5.x

• timeout is now the total display time in milliseconds. An old value of 30 becomes 3000.
• text is always plain text. Use html for markup and a sanitizer for untrusted HTML strings.
• show() returns the NoticeJs instance. Read the rendered element from notice.element.
• The old scroll option is removed. Use maxHeight.
• The documented callback list contains seven lifecycle callbacks. The old onTemplate entry is no longer part of the public callback API.
• The default closeWith value is now ['button', 'swipe'].
• The package ships plain CSS and no longer ships SCSS source files.
• IE11 is no longer supported. The JavaScript build targets ES2020.

Alternatives & Related Resources

• 10 Best Toast Notification JavaScript Libraries
• NotifyX: JavaScript Toast Notifications with AI Streaming
• Modern Toast Popup JavaScript Library – EggyJS

Changelog

v1.0.0 (09/26/2026)

• Rewritten in TypeScript with ESM, CommonJS, browser, and bundled type-definition outputs.
• Introduced promise notices, actions, update and close methods, ID deduplication, position limits, timer pausing, swipe dismissal, HTML sanitization hooks, and CSS custom properties.
• Added ARIA live regions, an accessible close button, Escape dismissal, modal focus handling, and reduced-motion behavior.
• Changed timeout semantics, text rendering, show return value, default dismissal methods, and browser baseline.
• Removed the old scroll option and SCSS package sources.

v0.5.0 (11/02/2025)

• Modernized the build setup and improved callback handling and documentation.