Dialog

Organism
A modal dialog: a centered panel over a dimmed backdrop, which glass on the web also blurs, 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.
src/organisms/dialog
View in Overlays & feedback

Playground

Every control sets a real prop of DialogProps. The JSX below updates as you go.
Props
title
string
description
string
Width
pick one
form
boolean
destructive
boolean
confirmLabel
string
cancelLabel
string
dismissible
boolean
JSX · DialogProps
<Dialog
title="Invite teammates"
description="They get edit access to this board only."
form
confirmLabel="Send invites"
cancelLabel="Cancel"
dismissible
/>

Variants

8 examples from src/organisms/dialog/dialog.md, each rendered live from its own JSX.
Application form
<Dialog form trigger="Edit project" title="Project details" description="Update the project name." footer={<Button primary>Save changes</Button>}>
<Input label="Name" defaultValue="Platform Core" />
</Dialog>
Dismissible
<Dialog trigger="Open details" title="Workspace details" dismissible />
Extra small
<Dialog trigger="Open dialog" title="Refund payment" xs />
Small
<Dialog trigger="Open dialog" title="Refund payment" small />
Medium
<Dialog trigger="Open dialog" title="Refund payment" medium />
Large
<Dialog trigger="Open dialog" title="Refund payment" large />
Wide
<Dialog trigger="Open dialog" title="Refund payment" wide />
Destructive action
<Dialog trigger="Delete workspace" title="Delete workspace" destructive confirmLabel="Delete" />

Anatomy

1
Scrim
2
Panel
3
Title
4
Description
5
Body
6
Actions
7
Close
Dimmed parts appear only in some states or variants.

Props

33 props on DialogProps, grouped as they are declared in source. Required props are marked *.
Prop
Type
Default
Description
Props
11 props
form
boolean
false
Structured form: a named header and close action above scrolling body/footer content.
workspace
boolean
false
Give an overlay form a viewport-bounded body that fills between its fixed header and footer.
compact
boolean
false
Let a workspace hug short content and grow only up to its viewport bound.
workspaceHeader
ReactNode
–
Extra content in the fixed header of a workspace form, below its title and description.
headerAccessory
ReactNode
–
Content beside the form title, such as a workflow's progress status.
workspaceSidebar
ReactNode
–
A fixed side rail beside a workspace's scrolling body.
footer
ReactNode
–
Custom actions after the form body; fixed below the body in workspace mode.
banded
boolean
false
Draw the reference's shared workflow panel as three bands split by hairline rules: the header (title, headerAccessory and optional workspaceHeader), body, and footer. A workspaceSidebar stays beside the body. Embedded panels keep their opaque in-page surface without a veil or close action; live panels keep modal presentation.
icon
ReactNode
–
A leading glyph for the panel, drawn as the accent's soft tone tile (Emblem primary soft) above the title. Pass an <Icon />; the tile tints and sizes it.
panelWidth
number
–
Maximum form panel width in pixels; defaults to 560.
children
ReactNode
–
Content
2 props
title
string
–
description
string
–
Body
1 prop
withBody
boolean
false
Trigger button label
1 prop
trigger
string
–
Action labels
2 props
confirmLabel
string
"Confirm"
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
–
Confirm intent
1 prop
destructive
boolean
false
Width
pick one
5 props
xs
boolean
false
small
boolean
false
medium
boolean
false
large
boolean
false
wide
boolean
false
Action handlers
8 props
onConfirm
() => void
–
Action handlers.
onCancel
() => void
–
Action handlers.
testID
string
–
E2E hook forwarded to the root element.

Accessibility and keyboard

Keyboard
Tab
Shift+Tab
Cycles focus inside the panel
Escape
Closes when dismissible
Enter
Confirms in forms
Semantics
Roles
alertdialog
button
dialog
heading
ARIA on web
aria-describedby
aria-label
aria-labelledby
aria-modal
From the docs
A modal dialog: a centered panel over a dimmed backdrop, which glass on the web also blurs, 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.
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.
Use form overlay dismissible for the original Argus application dialog: a persistent title and optional description, a close action, and scrolling body and footer content. panelWidth bounds the form (560 pixels by default), and the viewport keeps a twenty-pixel safe-area inset. The web treatment preserves Argus’s 28-pixel content inset, 17-pixel title, rounded card, shadow, and lightly frosted dim. A form with no trigger contributes no layout wrapper to its caller. Nested menus receive Escape before the dia

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

<Dialog
trigger="Open dialog"
title="Refund payment"
description="The refund posts to the original card in 2 to 3 business days."
withBody
/>
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.

Tokens

Read from the playground render. Values follow the scheme and the ion hue.
--bf
--bg2
--bls
--bw
--f-dp
--fd
--ft
--gl
--ion
--ion-fg
--ln
--ln2
--scrim
--sf3
--sh-lg
--tx
--tx2
--tx3

Related components