AlertDialog

AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes.

It implements the WAI-ARIA APG Alert Dialog pattern: role="alertdialog", a title linked by aria-labelledby, a consequence description linked by aria-describedby, focus moved into the dialog on open and returned to the trigger on close, and no dismissal by clicking outside. Escape cancels.

AlertDialog passes its requested width through to Dialog, which clamps the surface to the container and dynamic viewport with token gutters. Generic Dialog footers should wrap, but Dialog does not own action semantics or order; consumer composition controls that. AlertDialog owns its confirmation semantics: above 640px, actions render horizontally and may move onto another row; at 640px and below, the destructive action appears above Cancel and both buttons fill the footer width. Button labels retain their standard single-line behavior. The breakpoint follows available width, not pointer or hover capability. The body scrolls when block space is constrained.

For cases where you want to show an alert without managing open state, use the useImperativeAlertDialog hook: call alert.show(options) and render alert.element in your tree.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Alert Dialog

AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes.

It implements the WAI-ARIA APG Alert Dialog pattern: role="alertdialog", a title linked by aria-labelledby, a consequence description linked by aria-describedby, focus moved into the dialog on open and returned to the trigger on close, and no dismissal by clicking outside. Escape cancels.

AlertDialog passes its requested width through to Dialog, which clamps the surface to the container and dynamic viewport with token gutters. Generic Dialog footers should wrap, but Dialog does not own action semantics or order; consumer composition controls that. AlertDialog owns its confirmation semantics: above 640px, actions render horizontally and may move onto another row; at 640px and below, the destructive action appears above Cancel and both buttons fill the footer width. Button labels retain their standard single-line behavior. The breakpoint follows available width, not pointer or hover capability. The body scrolls when block space is constrained.

For cases where you want to show an alert without managing open state, use the useImperativeAlertDialog hook: call alert.show(options) and render alert.element in your tree.

Usage guidance

• Make the action button label specific: "Delete project" is better than "OK" or "Confirm".
• Describe what will happen in the description so the user knows the consequences before confirming.
• Keep the cancel button as the least-destructive focus target. On narrow screens the destructive action is visually and structurally above Cancel, but Cancel still receives initial focus.
• Use concise, specific action labels. Above 640px, complete buttons may move onto another row; at 640px and below, the destructive action appears above Cancel and both buttons fill the footer width.
• Avoid: Use AlertDialog for non-destructive actions; use a standard Dialog instead.
• Avoid: Rely on color alone to signal danger; the action label itself should say what will happen.
• Avoid: Close the dialog from onAction before the work finishes; hold it open with isActionLoading and call onOpenChange(false) when the action settles.

Theming API

{
  "targets": [
    {
      "className": "astryx-alert-dialog"
    }
  ]
}

useImperativeAlertDialog

Anatomy

• Title: The question being asked. Renders as a level-2 heading and labels the dialog via aria-labelledby.
• Description: What will happen if the user confirms. Linked to the dialog via aria-describedby.
• Cancel button: Ghost button that dismisses without acting. Takes initial focus, and Escape does the same thing.
• Action button: The confirming action. Destructive by default; shows a spinner while isActionLoading is set.
• Backdrop: Overlay behind the dialog that blocks page interaction. Clicking it does not dismiss.
• Dialog surface: The modal panel that holds the title, description, and buttons.

useImperativeAlertDialog

Hook for showing an alert dialog without managing open state. Call alert.show(options) to open and alert.hide() to close. Render alert.element in your JSX tree.

Examples

• AlertDialog — Delete: A delete button that asks the user to confirm before deleting.
• AlertDialog — Loading: A confirmation dialog that shows a spinner while the action runs.