If a user experience is a conversation, a dialog is like an interjection—it interrupts the current flow.

We use dialogs to provide useful information (FYI, some people call these “modals”). For example, dialogs can:

  • Give a more detailed explanation or definition
  • Guide the user through a series of steps
  • Ask the user to make a choice
  • Confirm that an action took place

In short, dialogs allow us to show different levels of information. If a design feels too complex, you can simplify the initial view and provide more detail inside a dialog.

How to use dialogs

  • Keep the text brief and factual. People tend to dismiss dialogs quickly, so get to the point.
  • Provide clear actions. Buttons work best.
  • Don’t annoy people. Dialogs are triggered by a user’s actions, so don’t show them arbitrarily.
  • Don’t hide important info in a dialog.
{% toggleText('single-button') %}
<div class="dialog">
  <div class="dialog-wrapper">
    <div class="dialog-head">
      <div class="dialog-heading">Example Heading</div>
      <a class="dialog-close">
          class="icon iconic iconic-sm"
    <div class="dialog-content">
      <div class="dialog-body">
        <p class="heading-display-small">Hello!</p>
          This is an example dialog modal. Normally, it would never appear within the main flow
          of a page. But, you know, this is an example.
        <p>What do you think?</p>
      <div class="dialog-actions">
        <div class="button-set">
          <div class="button-wrapper">
            <button class="primary button">Love It</button>
          <div class="button-wrapper">
            <button class="secondary button">Cancel</button>

Dialogs are designed to look like they’re floating above the main window. When opening the dialog, the user metaphorically takes a step backward in space. From their perspective, the main layer recedes and the dialog comes into focus. It’s important to keep the main layer in view so the user knows they can easily go back to what they were doing.

Dialog elements

Make sure to use a consistent structure for dialogs, as shown here.

Dialog heading
Short, simple, and descriptive.
Main message
Keep it brief. If the text feels wordy or confusing, people are more likely to dismiss it right away.
Prompt the user for a response, and provide a way to dismiss the dialog.

More examples

Explanation or definition


Special message

Dialog reference

Depending on what we need to communicate, we sometimes use a different dialog layout. Here are a few variations:

Class Description
Left-aligned text .text-align-left Aligns the text in the dialog to the left, instead of the default centered.
Small .small Sets the dialog width to 30% of the viewport, or a minimum of 300px. Good for short, simple messages.
Large .large Sets the dialog width to 80% of the viewport, or a maximum of 800px. Useful when you have longer content (probably means to you need to take another pass at editing).
Full .full Expands the dialog to fill the entire viewport.
Success dialog .success The background of the header uses the success color.
Alert dialog .alert The background of the header uses the alert color.