Accessible Alert

a11y-alert-dialog

Accessibility-first alert & dialog library that works without a mouse.

Accessible Alert is a framework-agnostic JavaScript library for displaying alert, confirm, and prompt dialogs with accessibility-first (a11y-first) design.

If you can use a keyboard, you can use this library.

✨ Why does this library exist?

Most alert/modal libraries:

• Prioritize visuals and animations
• Treat accessibility as an afterthought
• Break keyboard navigation and screen readers easily

👉 Accessible Alert is built the opposite way:

Accessibility is the foundation, not a feature added later.

✅ Accessibility Guarantees (A11Y Contract)

This library always guarantees:

• No mouse required
• Fully usable with keyboard only (Tab / Enter / Esc)
• Correct focus management at all times
• Focus is never lost after closing dialogs
• Proper screen reader announcements
• No auto-close behaviors that steal control from users

Standards:

• WCAG 2.1 AA
• WAI-ARIA Authoring Practices (Dialog)

📦 Installation

NPM

npm install a11y-alert-dialog

CDN

<script src="https://www.npmjs.com/package/a11y-alert-dialog"></script>

🚀 Basic Usage

Alert

await alert("Saved successfully")

Confirm

const ok = await confirm({
  title: "Delete user",
  description: "This action cannot be undone",
  danger: true
})

if (ok) {
  deleteUser()
}

Prompt

const name = await prompt({
  title: "Your name",
  placeholder: "Enter your name"
})

⌨️ Keyboard Behavior (Always Enabled)

| Key | Action | |----|-------| | Tab | Move forward within the dialog | | Shift + Tab | Move backward | | Enter | Confirm primary action | | Esc | Cancel / Close dialog |

Keyboard support cannot be disabled.

🧠 How Accessibility Is Handled

Focus Management

• Saves the currently focused element before opening
• Automatically moves focus into the dialog
• Restores focus to the original element after closing

Focus Trap

• Tab navigation is trapped inside the dialog
• Focus never escapes to the background
• No CSS hacks or pointer-event tricks

Screen Reader Support

• Uses role="dialog" or role="alertdialog"
• Proper aria-labelledby and aria-describedby
• Dialog content is announced immediately on open

🧩 API Design Principles

• Promise-based API
• No callbacks
• No configuration options that can break accessibility
• No custom HTML injection for critical controls

await confirm({ title: "Are you sure?" })

If an API allows breaking accessibility, the API is wrong.

❌ What This Library Does NOT Support

To protect accessibility, this library intentionally does NOT support:

• Auto-close timers
• Disabling focus trapping
• Custom button HTML
• Complex animations
• Theme systems
• Toast-style notifications

👉 If you want flashy UI effects, this library is not for you.

🧪 Testing philosophy

This library intentionally does not use automated browser testing.

Accessibility behavior such as keyboard navigation, focus management, and screen reader interaction cannot be reliably validated in headless or simulated environments.

Instead, this project relies on:

• Manual keyboard-only testing
• Screen reader testing (NVDA / VoiceOver)
• A strict accessibility contract defined in A11Y.md

This approach reflects real-world accessibility usage more accurately than flaky automated tests.

🎯 When Should You Use This Library?

✔ Internal tools
✔ Admin dashboards
✔ SaaS products
✔ Enterprise / Government / Fintech
✔ Any project where accessibility is a real requirement

📄 License

MIT

💬 Philosophy

“If you can use a keyboard, you can use this alert.”