Draft

Components

Dialog.

A modal that interrupts the flow for one decision — confirm, edit, or warn. It traps focus, dims the page behind a scrim, and returns focus to the trigger when it closes.

Overview

Title, body, and a footer where the primary action sits on the right.

Delete project?

This will permanently delete the project Central Office and all of its data. You won't be able to undo this action.

Anatomy

Title, body, and a footer where the primary action sits on the right.

Delete project?

This will permanently delete the project Central Office and all of its data. You won't be able to undo this action.

Part

Description

1. Header

Title + close-icon

2. Content

Body text, media, or form fields

3. Footer

Primary + Secondary actions

4. Surface

Background container

5. Scrim

Dimmed page overlay

Variants

Four fixed widths, from a single confirmation to a full-width workspace review.

Size

Use for

Small — 300px

Confirmations and single-decision alerts, e.g. "Delete this item?"

Medium — 500px

Standard forms and settings — default for most dialogs.

Large — 800px

Multi-field forms, comparisons, or content that needs room to breathe.

X-Large — 1140px

Complex editors or multi-column review screens. Use sparingly.

When to use

Confirmed in Material, Carbon, and Polaris — every one of them gives this its own standalone block, before any comparison to other components.

Use when

Don't use when

Confirming an important or potentially destructive action.

Requiring a decision before the user can continue.

Collecting short, focused input without leaving the page.

Displaying critical information that must be acknowledged.

The content is large or complex, or something the user needs to reference alongside the page — use a full page or Drawer.

The action is low-stakes and reversible — a Toast is enough.

A decision inside would trigger a second dialog — one dialog should never open another.

Choosing the right component

Picking the right component matters more than getting the dialog itself pixel-perfect. Use the table below to route to the right one.

Component

Use instead when

Dialog

A single, focused decision that must block the flow until resolved — confirm, edit one thing, or warn.

Drawer

The task needs more room, without leaving the page context.

Toast

Confirming something already happened — no response required.

Popover

Lightweight, anchored info tied to one element — not a full task.

Banner

A persistent, page-level message not tied to one action.

Menu / inline expansion

A small, fixed set of choices, or optional detail that doesn't need to block the flow.

Behaviour

How a dialog opens, closes, and responds while it's on screen.

Trigger

Result

Opening

Always triggered by an explicit user action (a button, link, or menu item).

Close icon

Closes without submitting any data. Always available unless the dialog requires an explicit acknowledgment.

Cancel button

Closes the dialog and discards any in-progress changes.

Scrim click

Closes light, dismissible dialogs. Disabled for dialogs collecting input, so an accidental click can't discard work.

Scrolling

Header and footer stay fixed; only the content area scrolls if the body is taller than the dialog.

Content

Dialog-specific writing rules. For general voice, grammar, and tone, see Voice & content.

Element

Rule

Title

Names the task as a short noun phrase or question — never a vague label like "Error" or "Confirm."

Body

States the consequence first if there is one, then what's being asked. Don't restate the title.

Buttons

A specific verb, plus a noun if the verb alone is ambiguous — "Delete file", not "OK" or "Yes".

Accessibility

A dialog that doesn't trap focus is a trap of a different kind.

Attribute

What it does

role="dialog"

On the panel, always paired with aria-modal="true".

aria-labelledby

Points at the title element, so screen readers announce the dialog by name.

aria-describedby

Optional — point it at a short plain-text message. Omit it if the body has lists, tables, or several paragraphs.

Focus trap

Tab and Shift+Tab cycle within the dialog; nothing behind the scrim is reachable.

Initial focus

Moves to the first interactive element — or the dialog itself if there is none.

Esc closes

Escape dismisses non-destructive dialogs; focus returns to the trigger.

Enter / Space

Activates the focused button. On a focused text field, Enter submits the dialog's primary action if the form is valid.

Scrim click

Closes the dialog for light, dismissible cases — never for destructive confirms.

Usage guidelines

What separates a dialog that respects the user's flow from one that fights it — shown, not just described.

Footer actions

Delete project?

This action can't be undone.

DoOne primary action in the footer, right-aligned, so the safe path is obvious.

Delete project?

This action can't be undone.

Don'tStack more than two primary actions — add a menu or a second screen instead.

Title phrasing

Delete project?

This action can't be undone.

DoA short noun phrase that names the decision.

Are you sure you want to permanently delete this project and all its associated data?

This action can't be undone.

Don'tA full sentence doing the work the body text is for.

Right-sizing

Delete file?

This action can't be undone.

DoSmall for a single trivial confirmation — content sets the size.

Delete file?

This action can't be undone.

Don'tUse a large dialog for content that fits comfortably in a small one.

Specifications

Title, body, and a footer where the primary action sits on the right.

Delete project?✕

This will permanently delete the project Central Office and all of its data. You won't be able to undo this action.

Container shapevar(--radius-4)

Container heightAuto

Container width300–1140px

Content min height100px

Title sizeTitle/Small Semibold

Body sizeBody/Medium Regular

Button sizeSmall

Icon size2x-large

Padding top / left / right / bottomvar(--space-m)

Padding between header and contentvar(--space-m)

Padding between icon and titlevar(--space-m)

Padding between content and footervar(--space-m)

Padding between buttons in footervar(--space-xs)

Shadowvar(--shadow-overlay)

Scrimrgba(0, 0, 0, 0.15)

Props (React)

type DialogProps = {
  open: boolean;
  onClose: () => void;          // Esc, scrim click, or close button
  title: string;                // wired to aria-labelledby
  children: ReactNode;          // body content
  footer?: ReactNode;           // actions — primary on the right
  size?: 'small' | 'medium' | 'large' | 'x-large'; // default 'medium'
  dismissible?: boolean;        // default true; false for destructive confirms
};

← PreviousBadge Next →Tabs