AlertDialog

Molecule

Catalyst-style confirmation dialog: a centered panel over a dimmed backdrop, which glass on the web also blurs, with a title, description, optional body, and action buttons. Reserve it for decisions that must block the rest of the app.

src/molecules/alert-dialog

View in Overlays & feedback

Playground

Every control sets a real prop of AlertDialogProps. The JSX below updates as you go.

Web

iOS

Android

Props

title

string

description

string

confirmLabel

string

cancelLabel

string

destructive

boolean

withInput

boolean

Width

pick one

default

narrow

small

large

JSX · AlertDialogProps

<AlertDialog

  title="Delete “Northwind”?"

  description="24 members lose access now. This cannot be undone."

  confirmLabel="Delete"

  cancelLabel="Cancel"

  destructive

/>

Variants

5 examples from src/molecules/alert-dialog/alert-dialog.md, each rendered live from its own JSX.

Narrow

<AlertDialog

  narrow

  title="Sign out?"

  confirmLabel="Sign out"

  trigger="Sign out…"

/>

Small

<AlertDialog

  small

  title="Transfer ownership?"

  description="You will lose admin access to this workspace."

  confirmLabel="Transfer"

  trigger="Transfer ownership…"

/>

Large

<AlertDialog

  large

  title="Transfer ownership?"

  description="You will lose admin access to this workspace, and the new owner can remove you from it. Billing, integrations, and the audit history move with the workspace."

  confirmLabel="Transfer"

  trigger="Transfer ownership…"

/>

Body field

withInput renders a confirmation field that gates the confirm action: the user must type the confirmText token (default "DELETE") exactly before the confirm button enables, so it is a real safety check rather than a decorative field. Pass confirmText to require a different token.

<AlertDialog

  title="Delete this identity?"

  description="This permanently removes the identity and revokes any active sessions. This action cannot be undone."

  confirmLabel="Delete"

  destructive

  withInput

  trigger="Delete identity…"

/>

Controlled

Drive the open state from outside the dialog: omit trigger, own open yourself, and pass onOpenChange so every way the dialog closes (confirm, cancel, browser Escape or iOS accessibility escape) reports back and keeps your state in sync. (Stateful is a docs-only state holder; in an app you would hold open with useState.)

<Stateful initial={false}>

  {(open, setOpen) => (

    <Column relaxed>

      <Button onPress={() => setOpen(true)}>Transfer ownership…</Button>

      <AlertDialog

        open={open}

        onOpenChange={setOpen}

        title="Transfer ownership?"

        description="You will lose admin access to this workspace."

        confirmLabel="Transfer"

/>

    </Column>

)}

</Stateful>

Anatomy

1

Scrim

2

Panel

3

Icon

4

Title

5

Description

6

Actions

Dimmed parts appear only in some states or variants.

Props

19 props on AlertDialogProps, grouped as they are declared in source. Required props are marked *.

Prop

Type

Default

Description

Content

2 props

title

string

–

description

string

–

Trigger button label

1 prop

trigger

string

–

Action labels

2 props

confirmLabel

string

"Continue"

Action labels.

cancelLabel

string

"Cancel"

Action labels.

Controlled open state

1 prop

open

boolean

false

Fired when the open state changes

1 prop

onOpenChange

(open: boolean) => void

–

Width

pick one

3 props

narrow

boolean

false

small

boolean

false

large

boolean

false

Body

2 props

withInput

boolean

false

confirmText

string

"DELETE"

The token the confirmation field must match to enable confirm (default "DELETE"). Only used when withInput is set; drives the placeholder ("type DELETE to confirm"), the field's accessible name, and the gate.

Confirm intent

1 prop

destructive

boolean

false

Action handlers

6 props

onConfirm

() => void

–

Action handlers.

onCancel

() => void

–

Action handlers.

overlay

boolean

false

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.

embedded

boolean

false

Show the open dialog as a non-modal specimen in the page, for a catalogue or a showcase: it keeps its look, its alertdialog role and its labelling, but does not take focus when it opens, trap Tab, return focus, claim aria-modal, or cancel on Escape or native back. Ignored with trigger, which always opens a live modal.

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.

Accessibility and keyboard

Keyboard

Tab

Shift+Tab

Cycles focus inside the panel

Escape

Closes when dismissible

Enter

Confirms in forms

Semantics

Roles

alertdialog

button

heading

States

disabled

ARIA on web

aria-describedby

aria-disabled

aria-labelledby

aria-modal

From the docs

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.

Platform skins

The playground's props on each platform: same tree, native shapes, type and touch sizes.

Web

control 10 · field 10 · card 16 · Instrument Sans

iOS

capsule controls · field 8 · card 12 · SF Pro · 44 pt

Android

Material 3 stadium · field 4 · card 12 · Roboto · 48 dp

Usage

<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…"

/>

On the web and Android the panel leads with a tone tile (a trash glyph on the destructive wash, otherwise an info glyph on the accent's), then a display title over its description, and closes on two equal buttons: a secondary Cancel and the primary or destructive confirm. On iOS it is the system alert: centered text over a two-cell action row under a hairline, the confirm in the error ink when destructive.

Tokens

Read from the playground render. Values follow the scheme and the ion hue.

--bad

--bad-fg

--bad-soft

--bf

--bg2

--bls

--bw

--f-dp

--fd

--ft

--gl

--hl

--ln

--ln2

--scrim

--sf3

--sh-lg

--tx

--tx2