Alert Dialog

Opinionated alert-dialog compound primitive built on Dialog.


Package	`@vizejs/ui/alert-dialog`
Maturity	stable
Own the source	`vize lib pull alert-dialog`
Requires	context, dialog, dismissable-layer, focus-guards, focus-scope, inert-outside, scroll-lock
Aliases	confirm dialog, destructive confirmation, modal alertdialog
Covers	WAI-ARIA alertdialog pattern, Radix Alert Dialog, Reka UI AlertDialog

Usage

import { AlertDialog, AlertDialogRoot, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger } from "@vizejs/ui/alert-dialog";

Or copy the source into your project with vize lib pull alert-dialog (see Source Distribution).

API

`AlertDialog`

Source: src/families/overlays/dialog/dialog-root.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned Dialog base id. `null` and `undefined` select a deterministic fallback.
`open`	`boolean`	`undefined`	Controlled open state. `undefined` selects uncontrolled behavior.
`defaultOpen`	`boolean`	`false`	Initial open state for uncontrolled use.
`modal`	`boolean`	`true`	Whether the dialog makes outside content inert, focus-contained, and scroll-locked.

Events

Event	Payload	Description
`update:open`	`[value: boolean]`	Fired when the Dialog requests a controlled open value.
`open-change`	`[value: boolean, previous: boolean, nativeEvent: Event \| null]`	Fired after any distinct open-state request.
`exit-complete`	`[]`	Fired once when an open dialog has fully closed, including without exit motion.

Slots

Slot	Slot props	Description
`default`	`DialogSlotState`	Compound Dialog children. Receives the current open and modal state.

Exposed

Member	Type	Description
`close`	—
`contentId`	—
`descriptionId`	—
`id`	—
`modal`	—
`open`	—
`openDialog`	—
`setOpen`	—
`state`	—
`titleId`	—
`toggle`	—

`AlertDialogRoot`

Source: src/families/overlays/dialog/dialog-root.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned Dialog base id. `null` and `undefined` select a deterministic fallback.
`open`	`boolean`	`undefined`	Controlled open state. `undefined` selects uncontrolled behavior.
`defaultOpen`	`boolean`	`false`	Initial open state for uncontrolled use.
`modal`	`boolean`	`true`	Whether the dialog makes outside content inert, focus-contained, and scroll-locked.

Events

Event	Payload	Description
`update:open`	`[value: boolean]`	Fired when the Dialog requests a controlled open value.
`open-change`	`[value: boolean, previous: boolean, nativeEvent: Event \| null]`	Fired after any distinct open-state request.
`exit-complete`	`[]`	Fired once when an open dialog has fully closed, including without exit motion.

Slots

Slot	Slot props	Description
`default`	`DialogSlotState`	Compound Dialog children. Receives the current open and modal state.

Exposed

Member	Type	Description
`close`	—
`contentId`	—
`descriptionId`	—
`id`	—
`modal`	—
`open`	—
`openDialog`	—
`setOpen`	—
`state`	—
`titleId`	—
`toggle`	—

`AlertDialogAction`

Source: src/families/overlays/dialog/dialog-close.vue

Props

Prop	Type	Default	Description
`type`	`"button" \| "reset" \| "submit"`	`"button"`	Native button submission behavior.
`disabled`	`boolean`	`false`	Remove the close button from activation and sequential keyboard focus.
`ariaLabel`	`string`	`undefined`	Accessible name when no visible label supplies one.

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before the button requests closing. Call `preventDefault()` to keep state unchanged.

Slots

Slot	Slot props	Description
`default`	`DialogSlotState & { readonly disabled: boolean }`	Close button contents. Receives the current Dialog state and button availability.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`focus`	—

`AlertDialogCancel`

Source: src/families/overlays/dialog/dialog-close.vue

Props

Prop	Type	Default	Description
`type`	`"button" \| "reset" \| "submit"`	`"button"`	Native button submission behavior.
`disabled`	`boolean`	`false`	Remove the close button from activation and sequential keyboard focus.
`ariaLabel`	`string`	`undefined`	Accessible name when no visible label supplies one.

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before the button requests closing. Call `preventDefault()` to keep state unchanged.

Slots

Slot	Slot props	Description
`default`	`DialogSlotState & { readonly disabled: boolean }`	Close button contents. Receives the current Dialog state and button availability.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`focus`	—

`AlertDialogContent`

Source: src/families/overlays/alert-dialog/alert-dialog-content.vue

Props

Prop	Type	Default	Description
`forceMount`	`boolean`	`false`	Keep content mounted while closed.
`trapFocus`	`boolean`	`true`	Contain focus inside an open modal alert dialog.
`autoFocus`	`boolean`	`true`	Move focus into content when it opens.
`restoreFocus`	`boolean`	`true`	Restore focus when content closes.
`inertOutside`	`boolean`	`true`	Make outside content inert while the modal alert dialog is open.
`lockScroll`	`boolean`	`true`	Lock document scroll while the modal alert dialog is open.
`closeOnEscape`	`boolean`	`true`	Let Escape request dismissal.
`closeOnPointerDownOutside`	`boolean`	`false`	Let outside pointer-down request dismissal.
`closeOnFocusOutside`	`boolean`	`false`	Let outside focus movement request dismissal.
`ariaLabel`	`string`	`undefined`	Accessible name when no visible title supplies one.
`ariaLabelledby`	`string \| null`	`undefined`	Space-separated ids that label the alert dialog. `null` omits the default title id.
`ariaDescribedby`	`string \| null`	`undefined`	Space-separated ids that describe the alert dialog. `null` omits the default description id.

Events

Event	Payload	Description
`open-auto-focus`	`[event: DialogAutoFocusEvent]`	Fired before automatic entry focus is applied.
`close-auto-focus`	`[event: DialogAutoFocusEvent]`	Fired before automatic focus restoration is applied.
`escape-key-down`	`[event: DismissableLayerEscapeKeyDownEvent]`	Fired before Escape requests dismissal.
`pointer-down-outside`	`[event: DismissableLayerPointerDownOutsideEvent]`	Fired before an outside pointer-down requests dismissal.
`focus-outside`	`[event: DismissableLayerFocusOutsideEvent]`	Fired before outside focus movement requests dismissal.
`interact-outside`	`[event: DismissableLayerInteractOutsideEvent]`	Fired before outside pointer or focus interaction requests dismissal.
`dismiss`	`[event: DismissableLayerDismissEvent]`	Fired after an unprevented dismissal request.

Slots

Slot	Slot props	Description
`default`	`AlertDialogSlotState`	AlertDialog content. Receives the current open and modal state.

Exposed

Member	Type	Description
`open`	`boolean`	Whether the dialog content is currently visible and interactive.
`modal`	`boolean`	Whether outside content is inert, focus-contained, and scroll-locked.
`state`	`DialogState`	Stable state token for styling and tests.
`element`	`HTMLDivElement \| null`	Rendered dialog content element.
`focusFirst`	`() => HTMLElement \| null`	Focus the first eligible descendant in the dialog content.
`focusContent`	`(options?: FocusOptions) => void`	Move focus to the content fallback target.

`AlertDialogDescription`

Source: src/families/overlays/dialog/dialog-description.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned description id. `null` and `undefined` use the Dialog default.
`as`	`PrimitiveAs`	`"p"`	Native element, custom element, or component to render.

Slots

Slot	Slot props	Description
`default`	—	Visible Dialog description.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.

`AlertDialogOverlay`

Source: src/families/overlays/dialog/dialog-overlay.vue

Props

Prop	Type	Default	Description
`forceMount`	`boolean`	`false`	Keep the overlay mounted while the dialog is closed.

Slots

Slot	Slot props	Description
`default`	`DialogSlotState`	Optional overlay contents. Receives the current Dialog state.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`modal`	—
`open`	—
`state`	—

`AlertDialogPortal`

Source: src/families/overlays/dialog/dialog-portal.vue

Props

Prop	Type	Default	Description
`to`	`string \| HTMLElement`	`"body"`	CSS selector or element the dialog layer is moved into.
`disabled`	`boolean`	`false`	Render in place instead of teleporting.
`defer`	`boolean`	`true`	Keep content in place until the target exists, avoiding SSR mismatch.
`forceMount`	`boolean`	`false`	Keep the portal host mounted while the dialog is closed.

Slots

Slot	Slot props	Description
`default`	`DialogSlotState`	Portalled Dialog layer contents.

Exposed

Member	Type	Description
`modal`	—
`open`	—
`present`	—
`state`	—

`AlertDialogTitle`

Source: src/families/overlays/dialog/dialog-title.vue

Props

Prop	Type	Default	Description
`id`	`string \| null`	`undefined`	Consumer-owned title id. `null` and `undefined` use the Dialog default.
`as`	`PrimitiveAs`	`"h2"`	Native element, custom element, or component to render.

Slots

Slot	Slot props	Description
`default`	—	Visible Dialog title.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.

`AlertDialogTrigger`

Source: src/families/overlays/dialog/dialog-trigger.vue

Props

Prop	Type	Default	Description
`type`	`"button" \| "reset" \| "submit"`	`"button"`	Native button submission behavior.
`disabled`	`boolean`	`false`	Remove the trigger from activation and sequential keyboard focus.
`ariaLabel`	`string`	`undefined`	Accessible name when no visible label supplies one.

Events

Event	Payload	Description
`click`	`[nativeEvent: MouseEvent]`	Fired before the trigger requests opening. Call `preventDefault()` to keep state unchanged.

Slots

Slot	Slot props	Description
`default`	`DialogSlotState & { readonly disabled: boolean }`	Trigger contents. Receives the current Dialog state and trigger availability.

Exposed

Member	Type	Description
`element`	`Readonly<ShallowRef<HTMLElement \| null>>`	Template ref to the rendered root element.
`focus`	—

Behavior

Normative state x input -> outcome table for alert-dialog-content.vue (@vizejs/ui/alert-dialog). Every row is proven by the named mounted-DOM, SSR, or compile-time test.

Surface	Contract
Root	`AlertDialogRoot` reuses Dialog controlled/uncontrolled state, deterministic ids, modal defaults, and slot/expose state.
Content	`AlertDialogContent` renders Dialog content with fixed `role="alertdialog"` and publishes an `alert-dialog-content` styling wrapper.
Dismissal	Outside pointer and focus dismissal are disabled by default; Escape and explicit action/cancel buttons may request closing.
Labelling	Title and description aliases keep Dialog deterministic id wiring for `aria-labelledby` and `aria-describedby`.
Styling	No component CSS is emitted beyond a scoped empty block; `data-vize-ui`, `part`, and `data-state` are the contract.
Packaging	Root and subpath consumers retain only AlertDialog plus required Dialog overlay utilities with zero CSS.

State x input	Outcome	Proven by
trigger click	Opens modal content with native `role="alertdialog"` and title/description id wiring.	`opens as a labelled modal alertdialog with explicit close actions`
outside pointer-down by default	Leaves the alert dialog open so destructive confirmations are not dismissed by backdrop accidents.	`opens as a labelled modal alertdialog with explicit close actions`
cancel or action click	Uses Dialog close semantics and restores focus to the trigger.	`opens as a labelled modal alertdialog with explicit close actions`
opted-in outside pointer-down	Emits the preventable outside event and closes when the event is not canceled.	`can opt into outside pointer dismissal`
SSR/hydration	Server markup is deterministic and contains no document-controller listeners or scroll-lock effects.	`renders deterministic alertdialog markup on the server`
public types and consumer bundle	TypeScript rejects a custom role, while root and subpath imports emit equivalent zero-CSS bundles.	`src/families/overlays/alert-dialog/alert-dialog.types.test-d.ts`, `scripts/check-tree-shaking.mjs`