Dialog

A modal dialog component for displaying content in an overlay.

Structured

Use variant="structured" with contentPadding="regions" for new dialogs. Dialog.Header holds the title row and Dialog.CloseButton. Dialog.Body scrolls. Dialog.Footer holds the actions; wrap dismiss actions in Dialog.Close asChild. Pass divider on the header and footer to separate them from a form body.

When you render Dialog.Title and Dialog.Description, pass hasAccessibleTitle and hasAccessibleDescription on Dialog.Content.

Controlled

Pass open and onOpenChange to open the dialog from your own state, for example a confirmation before a destructive action.

Default Variant

Omitting variant gives the legacy shell. Use it only to match an existing one-off layout. It has no regions and shows a close button in the top-right corner; pass showCloseButton={false} to hide it. Its panel has a 520px minimum width, so give it w-130 min-w-0 to let it shrink on small screens.

Usage

Without a visible Dialog.Title, pass aria-label on Dialog.Content. It renders a screen-reader-only title.


Parts

Dialog.RootRequired
DialogRootProps

Manages open state and modal behavior

Dialog.Trigger
DialogTriggerProps

Opens the dialog. Use asChild with a Button.

Dialog.ContentRequired
DialogContentProps

Portal, overlay, and panel

Dialog.Header
DialogHeaderProps

Title row, close button, and description

Dialog.Body
DialogBodyProps

Scrollable main region

Dialog.Footer
DialogFooterProps

Right-aligned action row

Dialog.Title
DialogTitleProps

Accessible dialog title

Dialog.Description
DialogDescriptionProps

Accessible dialog description

Dialog.CloseButton
DialogCloseButtonProps

Ghost icon button that closes the dialog. aria-label defaults to Close dialog.

Dialog.Close
ComponentPropsWithoutRef<typeof Close>

Radix close primitive. Use asChild to make a footer button close the dialog.

Dialog.Overlay
DialogOverlayProps

Backdrop. Dialog.Content renders it for you.

Dialog.Root Properties

open
boolean

Controlled open state of the dialog

onOpenChange
(open: boolean) => void

Callback fired when the open state changes

defaultOpen
boolean

Default open state of the dialog

Default: false

modal
boolean

Blocks interaction with content outside the dialog

Default: true

Dialog.Content Properties

variant
'default''structured'

Structured lays out Header, Body, and Footer. Default is the legacy shell.

Default: default

size
'md''lg''xl'

Structured only. md is 440px wide, lg is 640px with a 40vh minimum height, xl is 800px with a 60vh minimum height.

Default: md

contentPadding
'content''regions'

Structured only. regions moves the padding onto Header, Body, and Footer so dividers run full width. Prefer regions; don't combine with className="p-0".

Default: content

contentGap
'default''none'

Structured only. Gap between Header, Body, and Footer.

Default: default

showCloseButton
boolean

Renders the top-right close icon. Defaults to true for the default variant and false for structured.

hasAccessibleTitle
boolean

Set when children include Dialog.Title so no hidden title is added

Default: false

hasAccessibleDescription
boolean

Set when children include Dialog.Description so no hidden description is added

Default: false

disablePortal
boolean

Render in the current context instead of a portal

Default: false

hideOverlay
boolean

Do not render the dialog's own overlay

Default: false

overlayZIndex
'dialog''drawer'

Stacking layer. Use drawer to show the dialog above a drawer.

Default: dialog

overlayDarkerBackground
boolean

Use a darker overlay background

Default: false

overlayClassName
string

Additional CSS classes for the overlay

className
string

Additional CSS classes for the panel

onOpenAutoFocus
(event: Event) => void

Called when the dialog opens. Default focus is already prevented, so focus the element you want.

onCloseAutoFocus
(event: Event) => void

Called when focus returns to the trigger after the dialog closes

onEscapeKeyDown
(event: KeyboardEvent) => void

Called when Escape is pressed. Call event.preventDefault() to keep the dialog open.

onPointerDownOutside
(event: PointerDownOutsideEvent) => void

Callback fired when clicking outside the dialog

onInteractOutside
(event: CustomEvent) => void

Callback fired for any pointer or focus interaction outside the dialog. The event is a PointerDownOutsideEvent or a FocusOutsideEvent.

Region Properties

divider
boolean

Dialog.Header and Dialog.Footer: draws a border between the region and the body

Default: false

scrollShadow
boolean

Dialog.Body: fades the top and bottom edges while there is more to scroll. Structured only.

Default: false

viewportClassName
string

Dialog.Body: classes for the scrolling viewport when scrollShadow is set

focusRingInset
boolean

Dialog.Body: adds vertical padding so focus rings are not clipped under contentPadding="regions". Turn off when the body sets its own vertical padding.

Default: true

Dialog.Overlay Properties

zIndexRequired
'dialog''drawer'

Stacking layer relative to other modal surfaces

withBackdropBlur
boolean

Blurs the content behind the dialog

Default: true

darkerBackground
boolean

Uses a darker scrim

Default: false