Alert Dialog

A modal dialog that interrupts the user with important content and expects a response. Renders above the page and blocks interaction until dismissed.

Features

Focus trap
Initial focus
Inert outside
Portal rendering
Controlled or uncontrolled
Escape to close
Headless

Installation

npm install @ariaui/alert-dialog

Examples

Each row below is its own playground with a snippet from the same JSX. Open a dialog to verify focus trapping—Tab moves between controls and Escape dismisses to the matching Cancel behavior.

Destructive confirmation

Use when the primary action is irreversible or high-risk. Focus is trapped in the dialog; Cancel and Escape return to the page.

Preview

No preview output yet.

live.tsxReady

Framer Motion

Use asChild with Framer Motion to animate the overlay and content while preserving the destructive confirmation structure.

Preview

No preview output yet.

live.tsxReady

Anatomy

tsx

import * as AlertDialog from "@ariaui/alert-dialog";

export default function Example() {
  return (
    <AlertDialog.Root>
      <AlertDialog.Trigger />

      <AlertDialog.Portal>
        <AlertDialog.Overlay />
        <AlertDialog.Content>
          <AlertDialog.Icon />
          <AlertDialog.Title />
          <AlertDialog.Description />
          <AlertDialog.Cancel />
          <AlertDialog.Action />
        </AlertDialog.Content>
      </AlertDialog.Portal>
    </AlertDialog.Root>
  );
}

API Reference

Root

Context provider that owns open state. Renders no DOM element — wrap Trigger and Portal as children.

Prop	Type	Default
open	boolean	—
defaultOpen	boolean	—
onOpenChange	(open: boolean) => void	—

Trigger

The button that opens the dialog. Renders a <button> by default; use asChild to supply your own element.

Prop	Type	Default
asChild	boolean	false

Portal

Teleports Overlay and Content outside the current DOM tree into document.body, preventing stacking-context clipping.

Overlay

The backdrop layer rendered behind Content. Use data-state to drive open/close CSS animations.

Prop	Type	Default
asChild	boolean	false

Attribute	Values
[data-state]	open \| closed

Content

The dialog panel. Traps focus, sets role="alertdialog", and closes on Escape. Wrap Title and Description inside.

Prop	Type	Default
asChild	boolean	false

Attribute	Values
role	alertdialog (auto)
aria-modal	true (auto)
aria-labelledby	ID of Title (auto)
aria-describedby	ID of Description (auto)
[data-state]	open \| closed

Title

The dialog heading. Renders an <h2> and auto-registers its ID with Content for aria-labelledby.

Attribute	Values
id	Auto-generated; wired to Content aria-labelledby

Description

Supplementary text below the title. Renders a <p> and auto-registers its ID with Content for aria-describedby.

Attribute	Values
id	Auto-generated; wired to Content aria-describedby

Icon

Decorative icon slot. Renders a <span> with aria-hidden="true" so screen readers skip it.

Attribute	Values
aria-hidden	true (auto)

Cancel

The dismiss button. Closes the dialog on click without performing the destructive action.

Attribute	Values
data-alert-dialog-cancel	Present on the cancel button (auto)

Action

The confirm button. Closes the dialog on click after the destructive action is confirmed.

Keyboard

Shortcut	Action
`Space`/`Enter`	Open the dialog when focus is on the Trigger.
`Tab`/`Shift`+`Tab`	Cycle focus forward or backward through interactive elements inside the open dialog. Focus is trapped — it cannot leave Content.
`Esc`	Close the dialog and return focus to the Trigger.

Accessibility

The Alert Dialog component implements the WAI-ARIA Alert Dialog pattern. Content renders with role="alertdialog" and aria-modal="true". Title and Description are auto-wired via aria-labelledby and aria-describedby so screen readers announce the full context on open.

Always provide Title and Description

AlertDialog.Title and AlertDialog.Description are required for accessible announcements. Screen readers use them to identify the dialog's purpose and communicate the consequences of the action.

Use AlertDialog — not Dialog — for destructive actions

AlertDialog differs from a regular Dialog in that it does not close when clicking the Overlay. Users must explicitly choose Cancel or confirm. This enforces intentional interaction for irreversible operations.