Dialogs

General information

Related components

When to use

When not to use

Components contained within it

A dialog will generally consist of:

• At least one heading, with the first one acting as the accessible name of the dialog.
• Some content.
• At least one button that closes the dialog.

That’s the ultra-minimalist view. Some dialogs contain both a close “x” button up in a top corner and a “close” or “cancel” button at the bottom of the dialog. Some dialogs contain many more buttons; a wizard dialog might contain a close button, a back button, a next button, and a close “x” button. And the content can literally be anything, although we all prefer that you don’t put a ton of content in a dialog.

Per Deque University, the heading in a dialog should be an <h1> because it is a stand-alone view ¹. Conversely, I’ve had accessibility professionals tell me that dialogs should start with an <h2> because dialogs are structurally children of their base pages.

Honestly, I don’t think end users care particularly much as long as you pick one of those two options and then apply it consistently across your site’s dialogs. An <h3> would be too low down the hierarchy, and no heading at all means you have to apply some other accessible name for the dialog, so ensuring an <h1> is at the top with a reasonable title is your most efficient solution.

How to use

Anatomy

Do and do not

Options

Types

Sizes

States

Variants

Modifiers

Content standards

Animation standards

Interactions

Presentation

Placement

Hierarchy

Alignment

Composability

Responsive behavior

Spacing

Accessibility guidelines

Additional Resources

• React A11y Dialog by Kitty Giraudel
• Use the dialog element (reasonably) by Scott O’Hara
• We use too many damn modals by Adrian Egger
• What is a modal and when should I use one? by Jamie Juliver at Hubspot
• Dialogs on Carbon Design System
• Modal & Nonmodal Dialogs: When (& When Not) to Use Them by Therese Fessenden on Nielsen Norman Group