AlertDialog

Catalyst-style confirmation dialog: a centered panel over a dimmed, blurred backdrop, with a title, description, optional body, and action buttons. Reserve it for decisions that must block the rest of the app.
Browser Escape and iOS accessibility escape cancel the dialog, clear its confirmation field and request open=false. The confirmation text gates only the confirm action; cancellation remains available while confirm is disabled. An open child overlay handles dismissal first. A controlled owner can refuse closure without passing that request to a parent or calling onConfirm.
iOS
Android
Web
tsx
<AlertDialog
title="Delete this identity?"
description="This permanently removes the identity and revokes any active sessions. This action cannot be undone."
confirmLabel="Delete"
destructive
trigger="Delete identity…"
/>

Props

Prop
Description
title
string
Content (strings).
description
string
Content (strings).
trigger
string
Trigger button label. When set, the dialog renders the button and opens itself on press (uncontrolled). Omit when you drive `open` yourself.
confirmLabel
string
Action labels.
cancelLabel
string
Action labels.
open
boolean
Controlled open state. Omit for uncontrolled (the trigger opens it).
onOpenChange
(open: boolean) => void
Fired when the open state changes (trigger press, confirm, cancel).
narrow
boolean
Width (pick one; default is the medium panel).
small
boolean
Width (pick one; default is the medium panel).
large
boolean
Width (pick one; default is the medium panel).
withInput
boolean
Body: render a confirmation field that gates confirm. The user must type the `confirmText` token (default "DELETE") for the confirm action to enable; until it matches exactly, confirm is disabled and `handleConfirm` is a no-op. This is a real safety gate, not a decorative field.
confirmText
string
The token the confirmation field must match to enable confirm (default "DELETE"). Only used when `withInput` is set; drives the label, placeholder, and the gate.
destructive
boolean
Confirm intent (default is a primary confirm).
onConfirm
() => void
Action handlers.
onCancel
() => void
Action handlers.
overlay
boolean
Presents the confirm OVER the page instead of inline where it is mounted. The default is a contained overlay, which the docs catalogue needs to show one inside an example stage. An application asking to confirm a destructive action needs the opposite: inline, the scrim appears wherever the component happens to sit, the page behind stays scrollable and clickable, and the dialog still claims `aria-modal`. Teleports into the nearest `OverlayProvider`; with none in the tree it renders in place.
testID
string
E2E hook forwarded to the root element.
style
StyleProp<ViewStyle>
Outer layout composition only (width/flex within a parent), never a restyle hook.

Do & Don’t

Reserve the dialog for blocking decisions

Don’t
A blocking alert dialog for passive confirmation interrupts the user for no reason.
Do
Use an inline banner or toast for passive feedback; reserve the dialog for decisions that must be confirmed.

Name the action on the confirm button

Don’t
Generic Yes / No forces the user to re-read the title to know what they are confirming.
Do
Label the confirm button with the verb it performs (Delete, Archive, Sign out).

xs

Don’t
A long title, multi-line description, and wordy buttons get cramped in the xs width and wrap awkwardly.
Do
Reserve xs for a terse one-line question with short button labels and no body content.

sm

Don’t
Transfer ownership
New owner email
Reason
Type TRANSFER to confirm
Packing a multi-field form into sm makes it feel like a form crammed into a confirmation popup.
Do
Use sm for a single short confirmation with a one-line description; move real forms to a full dialog.

md

Don’t
Squeezing a description-carrying confirm into a smaller width crowds the copy against the edges.
Do
md is the default home for a typical destructive confirm with a sentence or two of description.

lg

Don’t
A bare yes/no in lg leaves a wide, empty panel that reads as heavier than the trivial decision it asks for.
Do
Reserve lg for dialogs that earn the width: a body field or a longer explanation to read.
← Alert
Card →