Alert Dialog

Overview

Alert Dialog is a modal dialog that interrupts the user with important content and expects a response. It self-portals to document.body, traps focus within the content while open, and restores focus to the trigger on close. Unlike a plain Dialog, initial focus lands on the Cancel control (so the destructive default is never the active target) and outside-pointer clicks never dismiss it; only Escape, Cancel, or Action close it.

Anatomy

@using Navius.Primitives.Components.AlertDialog

<NaviusAlertDialog>
    <NaviusAlertDialogTrigger />
    <NaviusAlertDialogBackdrop />
    <NaviusAlertDialogPopup>
        <NaviusAlertDialogTitle />
        <NaviusAlertDialogDescription />
        <NaviusAlertDialogCancel />
        <NaviusAlertDialogAction />
    </NaviusAlertDialogPopup>
</NaviusAlertDialog>

Root

Contains all the parts of an alert dialog. Owns the open state. Renders no DOM of its own.

Prop	Type	Default	Description
`Open`	`bool`	`false`	Controlled open state. Pair with `OpenChanged` (`@bind-Open`).
`OpenChanged`	`EventCallback<bool>`	-	Fires when the controlled `Open` value should change.
`DefaultOpen`	`bool`	`false`	Initial open state when used uncontrolled.
`ChildContent`	`RenderFragment?`	-	The alert dialog’s parts.

Trigger

The button that opens the dialog. Renders a button.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Trigger label content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `button`.

Portal

Optional wrapper that hoists the Backdrop and Popup to the portal target. Renders no DOM of its own.

Prop	Type	Default	Description
`Container`	`string?`	-	CSS selector for the mount target. `null` uses `document.body`.
`ForceMount`	`bool`	`false`	Keeps Backdrop and Popup mounted while closed, driving exit transitions off `data-closed` instead of unmounting.
`ChildContent`	`RenderFragment?`	-	The Backdrop and Popup.

Backdrop

The backdrop layer. Purely visual: clicking it never closes the dialog. Renders a div, portaled to the body.

Prop	Type	Default	Description
`KeepMounted`	`bool`	`false`	Keeps the backdrop mounted while closed, for exit animations.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

The focus-trapped panel. Renders a div with role="alertdialog", self-portaled to the body.

Prop	Type	Default	Description
`KeepMounted`	`bool`	`false`	Keeps the popup mounted while closed, for exit animations.
`OnOpenAutoFocus`	`EventCallback<NaviusOpenAutoFocusEventArgs>`	-	Fires when focus moves into the popup on open; cancelable.
`OnCloseAutoFocus`	`EventCallback<NaviusCloseAutoFocusEventArgs>`	-	Fires when focus returns to the trigger on close; cancelable.
`OnEscapeKeyDown`	`EventCallback<NaviusEscapeKeyDownEventArgs>`	-	Fires on `Escape`; cancelable.
`ChildContent`	`RenderFragment?`	-	The dialog’s content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `div`.

Title

An accessible name for the dialog (aria-labelledby on the Popup points here). Renders an h2.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Title content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `h2`.

Description

An accessible description for the dialog (aria-describedby on the Popup points here). Renders a p.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Description content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `p`.

Cancel

The cancelling action. Closes the dialog and receives initial focus. Renders a button.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Cancel button content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `button`.

Action

The confirming action. Closes the dialog. Renders a button.

Prop	Type	Default	Description
`ChildContent`	`RenderFragment?`	-	Action button content.
`Attributes`	`IDictionary<string, object>?`	-	Forwarded to the rendered `button`.

Data attributes

Part	Attribute	Description
Trigger	`data-popup-open`	Present while the dialog is open.
Backdrop	`data-open`	Present while open.
Backdrop	`data-closed`	Present while closing (through the exit transition).
Backdrop	`data-starting-style`	Present at the start of the open transition.
Backdrop	`data-ending-style`	Present at the start of the close transition.
Popup	`data-open`	Present while open.
Popup	`data-closed`	Present while closing (through the exit transition).
Popup	`data-starting-style`	Present at the start of the open transition.
Popup	`data-ending-style`	Present at the start of the close transition.

Keyboard interactions

Key	Behavior
`Space`	When focus is on the trigger, opens the dialog. When on Cancel or Action, activates it.
`Enter`	When focus is on the trigger, opens the dialog. When on Cancel or Action, activates it.
`Tab`	Moves focus to the next focusable element; focus is trapped within the content.
`Shift + Tab`	Moves focus to the previous focusable element; focus is trapped within the content.
`Escape`	Closes the dialog and returns focus to the trigger.

ARIA mechanism

The Trigger wires aria-haspopup="dialog", aria-expanded, and aria-controls pointing at the Popup’s id. The Popup renders role="alertdialog" with aria-modal="true", aria-labelledby pointing at the Title, and aria-describedby pointing at the Description. On open, focus moves to the Cancel control (the least destructive action) unless OnOpenAutoFocus is prevented, in which case the panel itself is focused; on close, focus is restored to the Trigger. Outside-pointer interaction never dismisses the dialog: only Escape and the explicit Cancel/Action controls close it. This implements the WAI-ARIA APG alert dialog pattern and is covered by the Playwright browser test suite and gated by axe-core in CI.