User Interface (UI)

Let's start with how a dialog looks: its parts, how wide it gets, what goes in it, how it shows that it's open and how to tune it.

Anatomy

Every dialog has a panel and a title. The title, the close button and the description sit in a header at the top, and the actions in a row at the bottom, so people always know what they're answering and how. The parts always render in the same order, which you can see in the DOM contract.

Sizes

The size prop sets how wide the dialog gets, at most, and md is the default. We recommend picking the smallest size that fits the content, since a short question in a wide panel leaves people reading lines that run across the screen.

<Dialog id="share" size="sm" title="Share project" open={open} onClose={() => setOpen(false)}>
  …
</Dialog>
{/* …md, lg */}

Sizes are set in rem, and the table shows the values we recommend at the default text size of 16px. Whatever its size, the dialog is never wider or taller than the screen, less 16px on each side, so on a phone 320px wide it fills the screen, with the page's edge still showing around it (WCAG 1.4.10). When its content is taller than that, the body scrolls, while the title and the actions stay in view.

Title, content and actions

A dialog's content goes in three places: a title and an optional description at the top, the body in the middle and the actions at the bottom.

<Dialog
  id="edit-profile"
  title="Edit profile"
  description="Your name and email address, as other people see them."
  open={open}
  onClose={() => setOpen(false)}
  actions={
    <>
      <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
      <Button color="primary" onClick={save}>Save changes</Button>
    </>
  }
>
  <label htmlFor="name">Full name</label>
  <Input id="name" autoComplete="name" />
  <label htmlFor="email">Email address</label>
  <Input id="email" type="email" autoComplete="email" />
</Dialog>

• The title says what the dialog is for, in a few words, like "Edit profile" or "Delete project?". It's also the dialog's name, so it's what screen readers announce as focus moves in, and what voice control users and agents find it by.
• The description is for a sentence or two that people need before they answer, like what a delete will take with it. Screen readers read it right after the title. Anything longer, like a form, a list or a table, goes in the body instead, which isn't part of the description, since screen readers would read it all out in one go, without its structure.
• The actions are Buttons, named by what they do. We recommend putting the one that leaves things as they are first, like Cancel, and the main one last, at the end of the row, so people read them, and Tab reaches them, in that order. Give the main action color="primary", or color="error" when it destroys something, and keep to one of them per dialog.
• The close button is an icon-only, ghost Button named "Close", which closeLabel translates. It sits at the top, beside the title, where people look for it.

States

The Dialog has two states of its own, open and closed, and the page around it has one too, since it's inert while the dialog is open.

Hover, focus and disabled belong to the controls inside a dialog, like its Buttons and Inputs, which show them the same way they do everywhere else. You'll find how each state behaves under Every state.

Tokens

The panel looks just like a Card, with the same padding, spacing, corners, border and type, so the two read as one family. Only its background differs, since it has to cover the page: it's Canvas, the background browsers give a native dialog, which follows color-scheme, so it fits your light and dark themes as long as they set it.

Its text reads one theme token, --color--neutral-text, like the Card's, and the backdrop is black at 50%, which dims a light page and a dark one alike. The Buttons inside read their own tokens, so copy tokens.css from the Button into your theme.

With our reference tokens, the title and the content come to 14.9:1 on white, and the description, at 70% of the text colour, to 5.6:1. The panel has a 1px border at 20% of the text colour, which also sets it apart on a dark page, where the backdrop barely shows. If you change the tokens or the background, make sure to check the same pairs.

If you need to tune a dialog, you can set its own variables, such as --dialog--width, --dialog--padding or --dialog--backdrop--background-color, from a class. The Dialog's styles sit in the components cascade layer, so your class wins without any specificity tricks:

import styles from "./Settings.module.css";

export function Settings({ open, onClose }: { open: boolean; onClose: () => void }) {
  return (
    <Dialog id="settings" title="Settings" className={styles.wide} open={open} onClose={onClose}>
      …
    </Dialog>
  );
}

.wide {
  --dialog--width: 60rem;
}

UI Checklist