Skip to contentSkip to navigation
DocsDocs

Dialog

A focused task over the page.

StableSince 1.0.0
On this page

Overview

Show code, ProjectDetails.tsx

Variants

Placement

Centered

Confirmations, short forms and details. The default.

Near the top

Search-like tasks, whose results grow down from a fixed field.

Show code, FindPlan.tsx

Widths

Both narrow to fit the window.

Medium

Most dialogs. The default.

Large

Tables, comparisons and longer forms.

Show code, ReviewChanges.tsx

Anatomy

  1. Dialog

  2. Title

  3. Description

  4. Content

  5. Close button

  6. Action

Show code, DialogAnatomy.tsx

Behaviour

Actions

A dialog's actions end with the primary one, after a built-in close button. A Cancel of your own is a secondary Button, as that close button is.

Pending work

While its work runs, nothing closes the dialog. Its close buttons are disabled, and its primary action shows the work running.

  • Submit a form from its primary action, so Enter in a field submits it too.
Show code, RenameProject.tsx

Closing actions

A DialogClose closes the dialog after doing its own work, such as Don’t save.

Show code, UnsavedChanges.tsx

Rules

One task per dialog, closed by its built-in button.

Use it when

  • A decision before a consequence, such as deleting a project
  • A short task that needs attention first, such as inviting a member
  • Content that needs more room than a popup, such as a comparison
  • A search-like task whose results grow below its field
DoThe built-in button named Cancel, for a decision.
Show code, CancelAsCloseLabel.tsx
Don’tA Cancel of your own beside the built-in Close.
Show code, ExtraCancelButton.tsx
DoA field's error on the field.
Show code, InviteMember.tsx
Don’tAn error in a second dialog over the first.
Show code, ErrorInSecondDialog.tsx

Accessibility

KeyAction
Tab, Shift+TabMoves through the dialog; a modal dialog keeps focus inside.
EscCloses the dialog, or first what is open inside it.
Enter, SpacePresses the focused button; a close button returns focus.

Related

  • Confirming one action in place that cannot be undone, such as removing a member from a list.

  • A question before one action, with Cancel and a button that names the consequence.

  • Details or a few fields beside the control that opens them.

  • Feedback after an action, such as Saved or Invitation sent.

  • A message about the page or a section that stays in place, such as a warning.

  • Quick open of a document or a command by name.

  • An item's details, settings or filters in a full-height panel at the edge of the window.

  • Items people keep open and work on beside the page, such as drafts.