Documentation and live examples v2.0.0

quick-alert

Alerts and toasts for Angular, React, Vue, and plain JavaScript. Try an example, then copy the code beside it.

Download & install

Install the package in any JavaScript project. It has no framework runtime dependency.

npm install quick-alert

Usage

Import the same API in every framework, then call fire() from a browser event.

import { quickAlert } from 'quick-alert';

const result = await quickAlert.fire({
  title: 'Saved',
  message: 'Your changes are ready.',
  type: 'success',
  buttons: 'ok'
});

console.log(result.action, result.dismissedBy);

On the server, importing the package is safe. Open alerts from a browser event or mounted component.

Examples

Each example opens the actual alert. The code on the right uses the same public API.

Last resultWaiting for an alert action

Success modal

Confirm and cancel actions with a promise result.

const result = await quickAlert.fire({
  title: 'Payment received',
  subtitle: 'Success modal',
  message: 'The customer has paid and the receipt is ready.',
  type: 'success',
  toast: false,
  buttons: 'confirm-cancel',
  confirmButtonText: 'View receipt',
  cancelButtonText: 'Later',
  showCloseButton: true
});

Toast with progress

A positioned toast with close button and progress bar.

quickAlert.fire({
  title: 'Toast notification',
  message: 'This toast closes by itself and shows a progress bar.',
  type: 'info',
  toast: true,
  position: 'top-right',
  showCloseButton: true,
  showProgressBar: true
});

Warning actions

Confirm, deny, and cancel buttons for destructive flows.

const result = await quickAlert.fire({
  title: 'Delete API key?',
  subtitle: 'This cannot be undone',
  message: 'Deny and cancel buttons make destructive confirmation flows clear.',
  type: 'warning',
  toast: false,
  buttons: 'confirm-deny-cancel',
  confirmButtonText: 'Review',
  denyButtonText: 'Delete key',
  cancelButtonText: 'Cancel',
  showCloseButton: true
});

Toast position

Move toast notifications to any supported screen position.

quickAlert.fire({
  title: 'Bottom-right toast',
  message: 'Position can be changed per alert.',
  type: 'success',
  toast: true,
  position: 'bottom-right',
  timeout: 3500,
  showProgressBar: true,
  showCloseButton: true
});

Button presets

Use one option for common action layouts.

const result = await quickAlert.fire({
  title: 'Delete item?',
  type: 'warning',
  buttons: 'confirm-cancel',
  confirmButtonText: 'Delete',
  cancelButtonText: 'Keep item',
  showCloseButton: true
});

Theme and ARIA labels

Use themes, variants, button classes, and accessible labels together.

quickAlert.fire({
  title: '',
  message: 'Theme, button variants, custom classes, and ARIA labels can be set per alert.',
  type: 'question',
  theme: 'dark',
  ariaLabel: 'Accessible themed alert',
  buttons: 'confirm-cancel',
  buttonVariant: 'outline',
  confirmButtonVariant: 'solid',
  confirmAriaLabel: 'Confirm themed alert',
  closeAriaLabel: 'Close themed alert',
  showCloseButton: true
});

Slot customClass

Style popup, overlay, icon, text, buttons, close button, and progress.

quickAlert.fire({
  title: 'Slot customClass',
  subtitle: 'Every visible slot can be styled',
  message: 'Pass classes for every alert slot.',
  type: 'warning',
  buttons: 'confirm-deny-cancel',
  showCloseButton: true,
  customClass: {
    popup: 'qa-demo-popup',
    overlay: 'qa-demo-overlay',
    confirmButton: 'qa-demo-confirm',
    progressBar: 'qa-demo-progress-bar'
  }
});

Queue modals

Open two modals and quick-alert keeps only one visible at a time.

quickAlert.fire({
  id: 'queue-first',
  title: 'First queued modal',
  toast: false
});

quickAlert.fire({
  id: 'queue-second',
  title: 'Second queued modal',
  toast: false
});

Stack toasts

Multiple toasts in the same position stack without overlapping.

quickAlert.fire({
  id: 'stack-one',
  title: 'Stacked toast one',
  toast: true,
  position: 'top-right'
});

quickAlert.fire({
  id: 'stack-two',
  title: 'Stacked toast two',
  toast: true,
  position: 'top-right'
});

Async confirm

Keep the modal open with a loading state while server work runs.

await quickAlert.fire({
  title: 'Verify on server',
  message: 'The confirm button enters loading state while preConfirm resolves.',
  type: 'warning',
  toast: false,
  buttons: 'confirm-cancel',
  confirmButtonText: 'Verify',
  preConfirm: () => new Promise(resolve => setTimeout(resolve, 900))
});

Pauseable timer

Pause timeout and progress while the toast is hovered or focused.

quickAlert.fire({
  id: 'pausing-timer',
  title: 'Pauseable timer',
  toast: true,
  timeout: 5000,
  pauseOnHover: true,
  pauseOnFocus: true,
  onTimerChange: (seconds, id) => console.log(id, seconds)
});

Safe custom content

Render safe DOM nodes without adding unsafe HTML parsing.

quickAlert.fire({
  title: 'Safe custom content',
  message: 'Fallback text is ignored when content is provided.',
  type: 'info',
  content: ({ document }) => {
    const list = document.createElement('ul');
    list.append('DOM node content', 'No innerHTML');
    return list;
  }
});

Lifecycle callbacks

Use lifecycle callbacks for analytics and event logs.

quickAlert.fire({
  title: 'Lifecycle callbacks',
  buttons: 'confirm-cancel',
  onOpen: ({ id }) => console.log('open', id),
  onConfirm: (result) => console.log('confirm', result.id),
  onCancel: (result) => console.log('cancel', result.id),
  onClose: (result) => console.log('close', result.dismissedBy),
  onTimeout: (result) => console.log('timeout', result.id)
});

Auto theme

Resolve default or dark styling from the user system preference.

quickAlert.fire({
  title: 'Auto theme',
  message: 'theme: auto resolves when the alert opens.',
  type: 'success',
  theme: 'auto',
  ariaLabel: 'Auto theme alert'
});

Global defaults

Configure shared defaults, then reset them when needed.

quickAlert.configure({
  type: 'info',
  toast: true,
  position: 'top-right',
  timeout: 3500,
  showProgressBar: true
});

quickAlert.fire({ id: 'docs-toast', title: 'Configured default' });
quickAlert.resetConfig();

Scoped defaults

Create isolated alert instances so defaults do not leak across app areas.

import { createQuickAlert } from 'quick-alert';

const billingAlert = createQuickAlert({
  type: 'question',
  position: 'center',
  toast: false,
  buttons: 'ok'
});

await billingAlert.fire({
  title: 'Scoped defaults',
  message: 'Only this alert instance receives these defaults.'
});

Close by API

Close one tracked alert by id, or clean up every active alert.

quickAlert.close('docs-toast');
quickAlert.closeAll();

Integrations

One root import works across frameworks. Use the call in a client event handler; no provider or plugin registration is required.

Angular

import { quickAlert } from 'quick-alert';

await quickAlert.fire({
  title: 'Saved',
  message: 'Angular uses the same API.',
  type: 'success'
});

React

import { quickAlert } from 'quick-alert';

<button onClick={() => quickAlert.fire({
  title: 'Saved',
  type: 'success'
})}>
  Save
</button>

Vue

<script setup lang="ts">
import { quickAlert } from 'quick-alert';

function save() {
  quickAlert.fire({ title: 'Saved', type: 'success' });
}
</script>

Plain JavaScript

import { quickAlert } from 'quick-alert';

document.querySelector('#save').addEventListener('click', () => {
  quickAlert.fire({ title: 'Saved', type: 'success' });
});

Next.js

'use client';

import { quickAlert } from 'quick-alert';

export function SaveButton() {
  return (
    <button onClick={() => quickAlert.fire({
      title: 'Saved from Next.js',
      theme: 'auto'
    })}>
      Save
    </button>
  );
}

Nuxt

<script setup lang="ts">
import { quickAlert } from 'quick-alert';

const notify = () => {
  quickAlert.fire({
    title: 'Saved from Nuxt',
    toast: true,
    theme: 'auto'
  });
};
</script>

SSR

import { quickAlert } from 'quick-alert';

// Safe during SSR: no document access happens until browser render.
await quickAlert.fire({ title: 'Browser-only UI' });

Themes

Select a built-in preset with theme. The auto preset follows the user's color scheme when the alert opens.

default

quickAlert.fire({
  title: 'default theme',
  theme: 'default',
  buttons: 'confirm-cancel'
});

dark

quickAlert.fire({
  title: 'dark theme',
  theme: 'dark',
  buttons: 'confirm-cancel'
});

auto

quickAlert.fire({
  title: 'auto theme',
  theme: 'auto',
  buttons: 'confirm-cancel'
});

success

quickAlert.fire({
  title: 'success theme',
  theme: 'success',
  buttons: 'confirm-cancel'
});

minimal

quickAlert.fire({
  title: 'minimal theme',
  theme: 'minimal',
  buttons: 'confirm-cancel'
});

glass

quickAlert.fire({
  title: 'glass theme',
  theme: 'glass',
  buttons: 'confirm-cancel'
});

material

quickAlert.fire({
  title: 'material theme',
  theme: 'material',
  buttons: 'confirm-cancel'
});

bootstrap

quickAlert.fire({
  title: 'bootstrap theme',
  theme: 'bootstrap',
  buttons: 'confirm-cancel'
});

Configuration parameters

Pass an options object to quickAlert.fire(). Global defaults can be set with configure(); use createQuickAlert() for isolated defaults.

Option	Default	What it does
`id`	`generated`	Identify an alert for close(id) and result tracking.
`title, subtitle, message, footer`	`''`	Text-only content in the four text areas.
`content`	`undefined`	Safe text, a DOM Node, or a browser-only DOM factory. Overrides message.
`type`	`'success'`	success, error, warning, info, or question icon.
`toast, position`	`false, center`	Choose modal or toast and where it appears.
`timeout, showProgressBar`	`4000, true`	Toast duration in milliseconds and progress visibility.
`pauseOnHover, pauseOnFocus, onTimerChange`	`true, true, none`	Pause a timed alert and observe the remaining seconds.
`buttons`	`automatic OK`	ok, confirm, confirm-cancel, confirm-deny-cancel, or none.
`showConfirmButton, showDenyButton, showCancelButton`	`false`	Legacy button flags when buttons is omitted.
`confirmButtonText, denyButtonText, cancelButtonText, okButtonText`	`action names`	Visible action labels.
`showCloseButton, showIcon`	`false, true`	Toggle the close control and state icon.
`theme, transition`	`default, slide`	Visual preset and fade or slide entrance.
`buttonVariant, [action]ButtonVariant`	`solid`	Use solid, outline, or ghost buttons globally or per action.
`[action]ButtonClass, customClass`	`''`	Add action classes or classes for individual alert slots.
`ariaLabel, [action]AriaLabel, closeAriaLabel`	`''`	Accessible labels for the dialog and controls.
`preConfirm, preDeny`	`undefined`	Async actions; returning false keeps the modal open.
`onOpen, onClose, onConfirm, onDeny, onCancel, onOk, onTimeout`	`undefined`	Lifecycle callbacks for UI work and analytics.

Options in action

Try the smaller options individually, then copy the option name from the reference table above.

Positions

Button layouts

Transitions and styling

Flows and timing

Handling buttons

fire() returns a promise. Read the action flag or the exact dismissedBy value.

const result = await quickAlert.fire({
  title: 'Delete item?',
  type: 'warning',
  buttons: 'confirm-cancel'
});

if (result.isConfirm) {
  console.log('Confirmed', result.id);
} else {
  console.log('Dismissed by', result.dismissedBy);
}

Result key	Meaning
`action`	confirm, deny, cancel, ok, close, or timeout.
`id`	The alert id supplied or generated when opened.
`dismissedBy`	The exact button, Escape, timeout, or API close.
`isConfirm, isDeny, isCancel`	Flags for a decision button.
`isOk, isClose, isTimeout`	Flags for acknowledgement or dismissal.

Handling dismissals

The dismissedBy field tells you how an alert ended, including Escape, timeout, and API close.

Reason	When it happens
`confirm-button, deny-button, cancel-button, ok-button`	An action button was pressed.
`close-button`	The close control was pressed.
`escape`	The modal was dismissed with Escape.
`timeout`	The timed alert finished.
`api-close`	close(id) or closeAll() dismissed the alert.

Icons

The five alert types use inline SVG icons. Set showIcon: false when an icon is not needed.

success

quickAlert.fire({
  title: 'success alert',
  type: 'success',
  buttons: 'ok'
});

error

quickAlert.fire({
  title: 'error alert',
  type: 'error',
  buttons: 'ok'
});

warning

quickAlert.fire({
  title: 'warning alert',
  type: 'warning',
  buttons: 'ok'
});

info

quickAlert.fire({
  title: 'info alert',
  type: 'info',
  buttons: 'ok'
});

question

quickAlert.fire({
  title: 'question alert',
  type: 'question',
  buttons: 'ok'
});

Methods

Method	Purpose
`quickAlert.fire(options)`	Open a modal or toast and await its result.
`quickAlert.close(id?)`	Close the matching alert or the current one.
`quickAlert.closeAll()`	Close active alerts and queued modals.
`quickAlert.configure(defaults)`	Set defaults for the shared controller.
`quickAlert.resetConfig()`	Restore the original defaults.
`createQuickAlert(defaults)`	Create an independent controller with scoped defaults.

quickAlert.configure({ theme: 'minimal' });

const billingAlert = createQuickAlert({
  type: 'info',
  position: 'top-right'
});
await billingAlert.fire({ title: 'Invoice sent', toast: true });

quickAlert.close('alert-id');
quickAlert.closeAll();
quickAlert.resetConfig();

Result log

readyOpen a demo alert