✦ Version 1.0 — Now Available
RoyalAlert
A beautiful, accessible, zero-dependency JavaScript popup library — alerts, toasts, confirmations, prompts & modals.
✦ Zero Dependencies
✦ Vanilla JS
✦ Accessible (A11y)
✦ TypeScript
✦ Dark Mode
✦ ~5KB gzipped
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/royal-alert/dist/royal-alert.min.css">
<script src="https://cdn.jsdelivr.net/npm/royal-alert/dist/royal-alert.min.js"></script>
npm install royal-alert
import RoyalAlert from 'royal-alert';
import 'royal-alert/dist/royal-alert.css';
⚡
Zero Dependencies
Pure Vanilla JS + CSS
🎨
CSS Variables
Infinitely customisable
♿
Accessible (A11y)
Focus trap, ARIA, Esc
🌙
Dark / Auto Mode
Follows OS preference
📱
Responsive
Mobile & tablet ready
🔷
TypeScript
Full type safety
🍞
9 Toast Positions
Stack & pause on hover
✅
Promise-Based
async / await friendly
🔌
WordPress Safe
No jQuery, no conflicts
🎞️
4 Animations
scale, fade, slide, flip
Why RoyalAlert?
The Ultimate Alternative
See how RoyalAlert compares to other popular solutions. Get all the features of a heavy library in a fraction of the size.
| Feature |
👑 RoyalAlert |
🍬 SweetAlert2 |
🍞 Toastify JS |
🖥️ Native JS |
| Gzipped Size |
~ 8.8 kB |
~ 21.0 kB |
~ 3.0 kB |
0 kB |
| Alerts & Modals |
✅ |
✅ |
❌ |
✅ (Basic) |
| Toast Notifications |
✅ |
✅ |
✅ |
❌ |
| Confirmations |
✅ |
✅ |
❌ |
✅ (Basic) |
| Input Prompts |
✅ |
✅ |
❌ |
✅ (Basic) |
| Async / Loading |
✅ |
✅ |
❌ |
❌ |
| Theme Support |
✅ (Auto/Dark) |
❌ (Separate CSS) |
❌ (Manual) |
❌ |
| Blocks UI? |
No |
No |
No |
Yes |
Examples
Basic Alerts
One-line calls for the most common scenarios. Each type comes with a matching icon and colour.
// Shorthand methods
RoyalAlert.success('Saved!');
RoyalAlert.error('Something went wrong.');
RoyalAlert.warning('Check your input.');
RoyalAlert.info('Update available.');
// Full control
RoyalAlert.fire({
type: 'success',
icon: 'success',
title: 'Profile Updated',
message: 'Your changes were saved.',
confirmText: 'Great!'
});
Interactions
Confirmations
Returns a Promise. Use await to know what the user chose. Supports 2 or 3 buttons.
const result = await RoyalAlert.confirm({
icon: 'warning',
title: 'Delete item?',
message: 'This cannot be undone.',
confirmText: 'Delete'
});
if (result.confirmed) deleteItem();
// 3-button dialog
const r = await RoyalAlert.fire({
title: 'Save changes?',
showDenyButton: true,
showCancelButton: true,
confirmText: '💾 Save',
denyText: "Don't save"
});
if (r.confirmed) save();
else if (r.denied) discard();
Notifications
Toast Notifications
Non-blocking toasts that stack, auto-dismiss, and pause on hover. Choose from 9 positions.
📍
Positions
9 placements across all corners and centers of the screen.
🎭
Types & Stacking
Multiple toasts stack independently. Each has its own timer. Hover to pause.
RoyalAlert.toast({
type: 'success',
title: 'File uploaded',
message: 'report.pdf saved to cloud.',
position: 'bottom-left', // default
duration: 3500, // ms — 0 = never dismiss
});
Async
Loading, Progress & Async
Block UI during async operations, track progress, and automatically transition to success or error.
⏳
Loading & Update
Open a spinner, update the message live, then close when done.
🌐
Async & fetch()
Wraps any Promise — shows loading, resolves to success or error automatically.
// Manual control
RoyalAlert.loading('Uploading…');
RoyalAlert.update({ message: 'Processing…', progress: 60 });
RoyalAlert.close();
// Auto-managed async
await RoyalAlert.async({
title: 'Saving to cloud…',
action: async () => {
const res = await fetch('/api/save', { method: 'POST' });
if (!res.ok) throw new Error('Server error');
},
successMessage: 'Saved!',
errorMessage: 'Could not save.'
});
Content
Custom HTML Modals
Embed any HTML content, custom images, and footer links inside a dialog.
🖼️
Rich Content
HTML body, custom images, footer strip, and scrollable long content.
🎛️
Custom Buttons
Full control over button text, colour, order, and click callbacks.
RoyalAlert.modal({
title: 'Terms of Service',
html: `<div style="text-align:left">
<p>By using <strong>RoyalAlert</strong> you agree to…</p>
</div>`,
footer: '<a href="#">Read full terms</a>',
imageUrl: 'https://picsum.photos/480/220',
confirmText: 'I Agree',
width: 600
});
Motion
Animations
Four CSS-driven entrance animations. All animations are disabled automatically when the OS has prefers-reduced-motion enabled.
📦
scale
Default. Scales up with a spring bounce.
🌅
fade
Smooth opacity transition.
⬇️
slide
Slides down from above.
🔄
flip
3D perspective entrance.
Theming
Themes & CSS Variables
Switch between light, dark, or auto (follows OS preference). Override any --ra-* CSS variable to match your brand.
☀️ Light
Clean white background, default
🌙 Dark
Deep navy surface, refined
⚙️ Auto
Follows your OS preference
/* Override CSS variables in your stylesheet */
:root {
--ra-primary: #6366f1; /* Confirm button, focus rings */
--ra-success: #10b981;
--ra-error: #ef4444;
--ra-bg: #ffffff; /* Card background */
--ra-radius: 24px; /* Card corner radius */
--ra-radius-btn: 9999px; /* Pill buttons */
--ra-overlay: rgba(15,23,42,.45);
}
// JS global config
RoyalAlert.config({
theme: 'auto', // 'light' | 'dark' | 'auto'
animation: 'scale', // 'scale' | 'fade' | 'slide' | 'flip'
position: 'bottom-left',
duration: 3000
});
Reference
API Reference
All methods, their signatures, and what they return.
RoyalAlert.fire(options)
Core method — opens any dialog. Returns Promise<Result>.
RoyalAlert.success(message)
Success alert with green icon.
RoyalAlert.error(message)
Error alert with red icon.
RoyalAlert.warning(message)
Warning alert with amber icon.
RoyalAlert.info(message)
Info alert with blue icon.
RoyalAlert.loading(message?)
Spinner dialog — closes only via .close(). Not dismissable by user.
RoyalAlert.toast(options)
Non-blocking notification. Stacks per position. Pauses on hover.
RoyalAlert.confirm(options)
Confirm + Cancel dialog. Returns { confirmed, cancelled }.
RoyalAlert.prompt(options)
Input dialog with optional async validator. Returns { confirmed, value }.
RoyalAlert.modal(options)
Flexible modal — HTML content, custom width, image, footer.
RoyalAlert.progress(options)
Determinate progress bar. Update with .update({ progress: 80 }).
RoyalAlert.async(options)
Auto-manages loading → success / error around a Promise.
RoyalAlert.request(options)
Native fetch() wrapper with loading states.
RoyalAlert.update(options)
Live-update title, message, or progress without closing.
RoyalAlert.close()
Programmatically close the topmost open dialog.
RoyalAlert.closeAll()
Close all open dialogs at once.
RoyalAlert.config(options)
Set global defaults. Per-dialog options always override these.
RoyalAlert.isOpen()
Returns boolean — true if any dialog is currently visible.
Result Object
| Property | Type | Description |
|---|
confirmed | boolean | User clicked the Confirm button |
cancelled | boolean | User clicked Cancel, ×, Esc, or the overlay |
denied | boolean | User clicked the Deny button (3-button dialogs) |
value | any | Input value (prompt), true (confirm), button ID (custom buttons) |
Key Options
| Option | Type | Default | Description |
|---|
type | string | 'info' | success / error / warning / info / question / loading |
title | string | — | Dialog heading |
message | string | — | Body text (XSS-safe, uses textContent) |
html | string | — | Raw HTML body (sanitise untrusted data yourself) |
confirmText | string | 'OK' | Confirm button label |
cancelText | string | 'Cancel' | Cancel button label |
showCancelButton | boolean | false | Show Cancel button |
showDenyButton | boolean | false | Show third Deny button |
inputType | string | 'text' | text / email / password / number / textarea / select |
inputValidator | function | — | async (value) → error string or void |
animation | string | 'scale' | scale / fade / slide / flip / none |
theme | string | 'light' | light / dark / auto |
timerProgressBar | boolean | false | Show shrinking bar when autoClose is on |
backdrop | string | — | Custom CSS background for overlay |
reverseButtons | boolean | false | Swap confirm / cancel positions |
closeOnEscape | boolean | true | Esc key closes dialog |
closeOnOverlay | boolean | true | Click outside to close |
Platforms
WordPress Integration
Drop RoyalAlert into any plugin or theme. No jQuery required. Zero conflicts with WP Admin or existing scripts.
// PHP — enqueue in your plugin
function my_plugin_scripts() {
wp_enqueue_style( 'royal-alert', 'https://cdn.jsdelivr.net/npm/royal-alert/dist/royal-alert.min.css' );
wp_enqueue_script( 'royal-alert', 'https://cdn.jsdelivr.net/npm/royal-alert/dist/royal-alert.min.js', [], '1.0.0', true );
wp_localize_script( 'royal-alert', 'myVars', [
'ajax_url' => admin_url( 'admin-ajax.php' ),
'nonce' => wp_create_nonce( 'my_nonce' )
]);
}
add_action( 'wp_enqueue_scripts', 'my_plugin_scripts' );
// JS — use in your script
const result = await RoyalAlert.confirm({ title: 'Delete this post?' });
if (result.confirmed) {
RoyalAlert.loading('Deleting…');
const fd = new FormData();
fd.append('action', 'delete_post');
fd.append('nonce', myVars.nonce);
await fetch(myVars.ajax_url, { method: 'POST', body: fd });
RoyalAlert.close();
RoyalAlert.toast({ type: 'success', message: 'Post deleted!' });
}
Source
Download & Use
You can download the compiled assets directly from GitHub or use the jsDelivr CDN.