Dialog

A modal dialog: a centered panel over a dimmed, blurred backdrop, with a title, an optional description, a body for real content like a form, and right-aligned actions. Use it for a focused task that warrants interrupting the page; reach for the Alert Dialog for a terse yes/no confirmation.
On light glass, the description and currency prefix use the stronger foreground color. For custom body content, use the default Typography foreground for message copy over the dimmed background.
Browser Escape and iOS accessibility escape cancel the foremost open child overlay before the dialog. Cancelling the dialog calls onCancel and requests open=false, including destructive dialogs and dialogs with custom children. A controlled owner may keep it open; that request never confirms an action.
Pass dismissible to let a backdrop press follow the same cancel policy. It is off by default, so existing dialogs and destructive confirmations keep their current outside-press behavior. The scrim is excluded from keyboard navigation.
iOS
Android
Web
tsx
<Dialog
trigger="Open dialog"
title="Refund payment"
description="The refund posts to the original card in 2 to 3 business days."
withBody
/>

Props

Prop
Description
children
ReactNode
—
title
string
Content (strings, for the children-less / data-driven case).
description
string
Content (strings, for the children-less / data-driven case).
withBody
boolean
Body: render a short form (Amount + Reason fields) inside the panel for the data-driven case.
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).
destructive
boolean
Confirm intent (default is a primary confirm).
xs
boolean
Width (pick one; default is the standard panel width). First-match precedence: xs, small, medium, large, wide.
small
boolean
Width (pick one; default is the standard panel width). First-match precedence: xs, small, medium, large, wide.
medium
boolean
Width (pick one; default is the standard panel width). First-match precedence: xs, small, medium, large, wide.
large
boolean
Width (pick one; default is the standard panel width). First-match precedence: xs, small, medium, large, wide.
wide
boolean
Width (pick one; default is the standard panel width). First-match precedence: xs, small, medium, large, wide.
onConfirm
() => void
Action handlers.
onCancel
() => void
Action handlers.
testID
string
E2E hook forwarded to the root element.
overlay
boolean
Presents the dialog OVER the page instead of inline where it is mounted. The default is a contained overlay: a scrim with its own height, sitting in normal flow, which is what the docs catalogue needs to show a dialog inside an example stage. An application confirming a destructive action needs the opposite, and the inline form is actively wrong there: it appends a scrim wherever the component happens to sit, leaves the page behind scrollable and clickable, and still claims `aria-modal`. With `overlay`, the dialog teleports into the nearest `OverlayProvider` and fills it, so `aria-modal` becomes true rather than aspirational. Mount an `OverlayProvider` at the app root for this to cover the screen.
dismissible
boolean
Cancel when the backdrop is pressed. Off by default, including destructive dialogs.
accessibilityLabel
string
The dialog's accessible name, for the case where `children` supply the panel body. Children REPLACE the built-in title/description, so there is no element left for `aria-labelledby` to point at, and the dialog would otherwise be announced with no name at all. That is merely poor for a `dialog` and invalid for the `alertdialog` a destructive confirm renders.
style
StyleProp<ViewStyle>
Outer layout composition only (width/flex within a parent), never a restyle hook.

Do & Don’t

When to use

Don’t

Delete file?

A bare yes/no question does not need the roomier Dialog; that is what the Alert Dialog is for.
Do
Use the Dialog for a focused task with real content, like a short form.

Description

Don’t
A multi-sentence policy dump in the description buries the task under reading.
Do
Keep the description to one supporting line; link out for the full policy.

Body form

Don’t
A seven-field form crammed into a small dialog feels like a page stuffed into a popup.
Do
Keep the body to the few fields the task needs; send long forms to a full page.

Actions

Don’t
Three look-alike primary buttons give no signal about the default, safe choice.
Do
One primary plus quieter secondaries, right-aligned and labeled with their verb.

Destructive action

Don’t

Save changes

Update the profile with your edits.
A red button on a routine Save trains users to ignore the colour that should mean danger.
Do

Delete workspace

This removes all projects and cannot be undone.
Reserve the destructive tone for the irreversible action it names.

Size

Don’t
A 2xl panel around a single field leaves a vast empty expanse beside the input.
Do
Size the dialog to its content: a single field belongs in xs or sm.
← DataTable
Drag & drop →