Dialog

A dialog is a centered overlay on a scrim for something people must finish before they continue: a decision, or a small task of a few fields, such as creating a channel. It has a title, a body and at most two buttons. Its wide size holds a large form filled in one pass. To confirm an action, use AlertDialog.

跟随页面浅色深色并排

When to use

Which overlay fits which job is in Choosing a component.

Anatomy

• Dialog: the root. Owns the open state. Required.
• DialogTrigger: the button that opens it.
• DialogContent: the centered surface, portaled, with the scrim (DialogOverlay) behind it. Required.
• DialogHeader: the title row, with an optional DialogClose at its end. The × is pulled out so its icon box, not the button, ends on the dialog's 20px margin (Alignment).
• DialogTitle: the title. Required.
• DialogDescription: a sentence under the title or in the body.
• DialogBody: the content. It scrolls when the dialog reaches the window height.
• DialogFooter: the buttons, aligned to the end.
• DialogClose: closes the dialog. Without children it is the × icon button; with render it turns a Cancel button into a close button.
• DialogNav: the section list of a wide dialog.
• DialogSurface: the dialog's frame without Base UI behind it, for a centered modal whose app owns the backdrop, Esc and focus, such as search.
• DialogPortal and DialogOverlay: lower-level parts.

Variants

Pick the size by what the dialog holds, not by what looks right. The four sizes are far enough apart that each holds one kind of content (cindyz, 2026-10-21):

• Every confirmation is one width, 400px, whether it is built on Dialog or AlertDialog. A confirmation whose content no longer fits 400px isn't a confirmation any more: it is a small task, at md.
• sm, md and lg are the small dialog: its height follows its content, up to the window less 32px, and a click on the scrim closes it. wide is the large form dialog.
• Set the width with size only. Product code never passes its own max-w-* to DialogContent. Content that fits none of the four sizes isn't a dialog: make it a page or a Drawer.
• Only these overlays have a width outside the four sizes, each set by its own rule. Nothing else may add one:
  • Task details, 960px: a workspace overlay (Tasks).
  • Search, 720px, on DialogSurface, its top edge over the top bar's field (Search).
  • The showcase frame, 720px wide and about 520px high, shared by steps 3 to 5 of onboarding and the Upgrade to Pro dialog, and used by nothing else (Onboarding).
  • AnnouncementDialog, 576px: its picture and one-paragraph text read best there; at 640px the text runs past 80 characters a line.
  • An attachment preview, as wide as the file needs, up to 768px.
• On a narrow screen every size is as wide as itself or the window less 32px, whichever is smaller, so at 390px each one is 358px wide. Its height and the wide dialog's sections are in Behavior.

The large form dialog uses bar on DialogHeader, DialogBody and DialogFooter: the header and footer stay in place and the body scrolls between them. The body holds DialogNav on the left, a line-seam after it, and one FormSection per section on the right. Its structure and rules are in Forms.

Behavior

• A centered dialog appears and disappears without animation, always over the scrim (Motion). On a phone a dialog with fields is a sheet that slides up instead (On a phone).
• Esc, × and Cancel close a dialog. A click on the scrim closes a small dialog.
• Don't close a large form dialog on a click outside it: pass disablePointerDismissal on Dialog, so a half-filled form isn't lost to a stray click.
• A centered dialog on a narrow screen keeps a 16px margin on each side and never grows taller than the window less 32px.
• Below 768px the wide dialog hides DialogNav and the sections follow one another.
• A dialog opened from a dialog or a sheet draws its own, lighter scrim over the one below (Stacked overlays). Render it inside the first one and this happens by itself. layer={1} is only for a dialog rendered outside the first one's tree: it lifts the dialog and its scrim above the first.

On a phone

Below 768px a dialog stays centered unless it has several fields, a long list or steps, in which case it becomes a sheet (stdrc and Artea, 2026-10-21). On a desktop and a tablet every dialog stays centered.

The sheet:

• Rises from the bottom over the scrim, with radius-dialog on its top corners. The strip of page left above it shows that it is a layer over the page, not a new page.
• Its head is a pushed page's head (Navigation): × at the start, the title, and the dialog's one commit button at the end, at size md with the same color and words as on a desktop. It has no footer: × is Cancel. In a flow of steps the button at the end is the step's (Next, then the last step's action), and × still closes.
• The body scrolls under the head and keeps the phone's 16px margin and the home indicator's inset at the bottom.
• × and Esc close it. A tap on the scrim doesn't, so a half-filled form isn't lost to a stray tap, as with a large form dialog on a desktop. When something has been typed, ask before closing.
• Dragging the sheet down to close it is planned, for when the sheet moves into raft-ui on top of Drawer's drag.
• It slides up as it opens, like every bottom sheet (Motion).

Raft Chat builds these forms in the app for now (NarrowDialog in slock); they move into raft-ui as a phone presentation of Dialog.

Content

• Title the dialog with the words of the button that opened it, or Edit and the item's name. Label its main button with the action it performs, without the object: usually the title's verb (Create Channel → Create); an Edit title's button is Save, and the other one Cancel (Writing).
• Set body text in foreground-muted, below a title in foreground. Their type styles are in Typography.

Accessibility

• Dialog wraps the Base UI Dialog. It provides the dialog role, the focus trap, Esc and focus return to the trigger.
• Give every dialog a DialogTitle. It becomes the dialog's accessible name, and it is what a screen reader announces on open.
• DialogDescription becomes the dialog's description.
• The × of DialogClose is labeled "Close". Pass aria-label to change it.
• DialogSurface has no behavior of its own. The app that uses it must add the dialog role, aria-modal, a name, the focus trap, Esc and the scrim.

Rules

• Put at most two buttons in the footer: Cancel on the left (variant="ghost"), the confirm button on the right.
• Make the confirm button pink (variant="primary") when it does something. Color it by its consequence when it interrupts or can't be undone (AlertDialog).
• Put anything people must read before they act in a Banner inside the body (Feedback).
• Pad every size by 20px. Its width comes from size (Variants), never from a class of your own.
• Don't pass overlay={false} in product code: every centered dialog has the scrim, without exception.