---
url: /components/dialogs/guidelines.md
description: >-
Dialogs provide important prompts in a user flow. Use dialogs to make sure
users act on information
---
# Dialogs
Dialogs provide important prompts in a user flow. Use dialogs to make sure users act on information
[Overview](overview.md) · [Specs](specs.md) · **Guidelines** · [Accessibility](accessibility.md)
A basic dialog
## Usage
A dialog is a modal window that appears in front of app content to provide critical information or ask for a decision. Dialogs disable all app functionality when they appear, and remain on screen until confirmed, dismissed, or a required action has been taken.
Dialogs are purposefully interruptive, so they should be used sparingly. A less disruptive alternative is to use a dropdown [menu](../menus/overview.md "Menus display a list of choices on a temporary surface."), which provides options without interrupting a user’s experience.
There are two variants of dialogs:
1. Basic dialog
2. Full-screen dialog
::: tip Do
Use dialogs for prompts that block an app’s normal operation, and for critical information that requires a specific user task, decision, or acknowledgement
:::
::: danger Don't
Don’t use dialogs for low- or medium-priority information. Instead use a snackbar, which can be dismissed or disappear automatically.
:::
### Similar components
[Snackbars](../snackbar/overview.md "Snackbars show short updates about app processes at the bottom of the screen.") are also designed to show important messages.
Choose the right component based on the importance of the message. This component messaging strategy helps avoid overusing dialogs.
Snackbars can disappear automatically
| **Component** | **Importance** | **Action needed** |
| ------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Snackbar | Low importance | Optional: Snackbars may not have a [button](../buttons/overview.md "Buttons let people take action and make choices with one tap."), and can disappear automatically |
| Dialog | High importance | Required: Dialogs block the main content until an action is confirmed |
## Anatomy
### Basic dialog
1. Container
2. Icon (optional)
3. Headline (optional)
4. Supporting text
5. Divider (optional)
6. Buttons label text
7. Scrim
### Full-screen dialog
1. Container
2. Header region
3. Icon (close affordance)
4. Headline (optional)
5. Button label text
6. Divider (optional)
### Container and scrim
Dialog containers appear above other screen elements and hold the dialog’s headline, text, [buttons](../buttons/overview.md "Buttons let people take action and make choices with one tap."), and [list](../lists/overview.md "Lists are continuous, vertical indexes of text and images.") items.
To focus attention on the dialog, surfaces behind the container are scrimmed with a temporary overlay to make them less prominent.
Basic dialogs appear over a background scrim
### Headline (optional)
A dialog’s purpose should be communicated by its headline and buttons or actionable items.
Headlines should:
* Contain a brief, clear statement or question
* Avoid apologies (“Sorry for the interruption”), alarm (“Warning!”), or ambiguity (“Are you sure?”)
::: tip Do
This dialog title poses a specific question, concisely explains what’s involved in the request, and provides clear actions
:::
::: danger Don't
Don’t use dialog titles that pose an ambiguous question
:::
Headlines should always be succinct. They can wrap to a second line if necessary, and be truncated.
In full-screen dialogs, long headlines or headlines of variable lengths (such as translations), can be placed in the content area instead of the app bar.
::: warning Caution
Avoid placing long headlines in a full-screen dialog’s app bar (1), as the truncated text may lead to misunderstanding
:::
::: tip Do
Find ways to shorten app bar text, and place longer headlines into the content area (1) of a full-screen dialog
:::
### Buttons
Dialog actions are most often represented as [buttons](../buttons/overview.md "Buttons let people take action and make choices with one tap.") and allow users to confirm, dismiss, or acknowledge something.
Buttons are aligned to the trailing edge of the dialog for easier interaction. The confirmation button is always closest to the edge.
Button alignment responds automatically for right-to-left languages, where the confirmation button is aligned to the left edge.
::: tip Do
Disable confirming actions (1) until a choice is made. Dismissive actions are never disabled.
:::
::: danger Don't
Don’t place dismissive actions (1) to the right of confirming actions. Instead, place them to the left of confirming actions.
:::
::: tip Do
A single action may be provided only if it’s an acknowledgement
:::
::: danger Don't
Avoid presenting people with unclear choices. **Cancel** doesn't make sense here because no clear action is proposed.
:::
Dialogs should contain a maximum of two actions.
* If a single action is provided, it must be an acknowledgement action
* If two actions are provided, one must be a confirming action, and the other a dismissing action
::: tip Do
Display two text buttons next to one another
:::
::: warning Caution
Stacked buttons accommodate longer button text, but take up more room. Confirming actions appear above dismissive actions.
:::
Providing a third action, such as **Learn more**, is not recommended as it navigates the user away from the dialog, leaving the dialog task unfinished.
Rather than adding a third action, an inline expansion can display more information. If more extensive information is needed, provide it prior to entering the dialog.
::: warning Caution
The **Learn more** action (1) navigates away from this dialog, potentially leaving it in an indeterminate state
:::
## Basic dialog
Basic dialogs interrupt users with urgent information, details, or actions. Common use cases for basic dialogs include alerts, quick [selection](../../foundations/interaction/selection.md "Selection lets users choose specific items to act on."), and confirmation.
Basic dialogs require a person to take action before it will close
Basic dialogs can give people the ability to provide confirmation of a choice before committing to it
Basic dialogs most often appear as alerts or [lists](../lists/overview.md "Lists are continuous, vertical indexes of text and images."), but can have a variety of [layouts](../../foundations/layout/layout-overview/overview.md "Layout is the visual arrangement of elements on the screen.") and component combinations, including lists, [date pickers](../date-pickers/overview.md "Date pickers let people select a date, or a range of dates."), and [time pickers](../time-pickers/overview.md "Time pickers help users select and set a specific time.").
Date picker dialogs allow people to tap a date, then confirm it by tapping **OK**
Time picker dialogs allow people to move the clock hand and then confirm by tapping **OK**
## Full-screen dialog
Full-screen dialogs fill the entire screen, containing actions that require a series of tasks to complete. One example is creating a calendar entry with the event title, date, location, and time.
Because they take up the entire screen, full-screen dialogs are the only dialogs over which other dialogs can appear.
Use a [container transform](../../styles/motion/transitions/transition-patterns.md#b67cba74-6240-4663-a423-d537b6d21187) pattern to transition a [FAB](../floating-action-button/overview.md "Floating action buttons (FABs) help people take primary actions.") into a full-screen dialog.
Full-screen dialogs contain actions that require a series of tasks to complete
When a full-screen dialog is closed without being saved, a basic dialog appears in front of it to confirm [selections](../../foundations/interaction/selection.md "Selection lets users choose specific items to act on.") should be discarded without saving changes.
A basic modal dialog appears when a full-screen dialog is closed without being saved
Full-screen dialogs may be used for content or tasks that meet any of these criteria:
* Dialogs that include components which require keyboard input, such as form fields
* When changes aren’t saved instantly
* When components within the dialog open additional dialogs
Full-screen dialogs are for [compact breakpoints](../../foundations/layout/breakpoints/compact.md "Window widths smaller than 600dp, such as a phone in portrait orientation.") only, like mobile devices. For medium and [expanded breakpoints](../../foundations/layout/breakpoints/expanded.md "Window widths 840dp to 1199dp, such as a tablet or foldable in landscape orientation, or desktop."), use a basic dialog.
### Saving selections
To save a selection in a full-screen dialog, use **Save**. The close icon or dismissive action, such as **Cancel** or **Back**, should close the dialog.
### Confirmation
The confirmation action should be clear about what happens next, like **Send** or **Create**. Avoid using vague terms like **Done**, **OK**, or **Close**. Only trigger an additional basic dialog if the action fails. Don’t [disable](../../foundations/interaction/states/applying-states.md#4aff9c51-d20f-4580-a510-862d2e25e931 "A disabled state communicates an inoperable component or element.") the confirmation button.
::: tip Do
A **Create** button is clear that the event will be created
:::
::: danger Don't
Don’t trigger a basic dialog when the confirming action is selected
:::
### Dismissing
When someone dismisses a full-screen dialog, a basic dialog should appear to confirm that they want to discard the unsaved changes.
::: tip Do
Use a basic dialog to confirm that the user wants to discard unsaved changes
:::
::: danger Don't
Don’t use the confirming action to dismiss the full-screen dialog
:::
### Error messages
Errors about the dialog fields should always appear inline where they occur. Some components like [text fields](../text-fields/overview.md "Text fields let users enter text into a UI.") have built-in error messaging, while others like [checkboxes](../checkbox/overview.md "Checkboxes let users select one or more items from a list, or turn an item on or off.") and [radio buttons](../radio-button/overview.md "Radio buttons let people select one option from a set of options.") need error messages to be added next to the fields.
General errors such as network issues preventing saving or submitting should appear in a basic dialog when the confirming action fails.
Error messages should clearly but briefly explain the source of the error and how to fix it. Show all errors on the page at once so people can fix everything before trying again.
::: tip Do
Error messages related to the fields should be displayed inline
:::
::: warning Caution
Errors unrelated to the fields can be displayed in a basic dialog
:::
### Dialog windows
Launching a full-screen dialog temporarily resets the app’s perceived elevation, allowing simple [menus](../menus/overview.md "Menus display a list of choices on a temporary surface.") or dialogs to appear above the full-screen dialog. They cover the screen and don’t appear as a floating modal window.
### Navigation
Because full-screen dialogs can only be completed, dismissed, or closed, the close “X” icon button should be the only navigation option in the [app bar](../app-bars/overview.md "App bars display information and actions at the top of a screen.").
## Adaptive design
Dialogs can swap variants as the [breakpoint](../../foundations/layout/breakpoints/overview.md "Breakpoints are opinionated window sizes where a layout changes to match available space, device conventions, and ergonomics (previously window size classes).") changes. For example, a [full-screen dialog](#007536b9-76b1-474a-a152-2f340caaff6f "Full-screen dialogs fill the entire screen, displaying actions that require a series of tasks to complete. They're often used for creating a calendar entry.") can change into a [basic dialog](#97ac3858-3932-4084-ae8e-73e42b7cb752 "Basic dialogs interrupt users with urgent information, details, or actions. They're often used for alerts, quick selection, or confirmation.") at larger breakpoints.
1. Full-screen dialog on mobile
2. Dialog on a tablet
### Medium breakpoint
Basic dialogs appear in a center position by default.
Their position can be overridden to provide a more ergonomic experience.
Dialog custom positioned on the right side of the screen
### Expanded breakpoint
Dialogs on [expanded breakpoints](../../foundations/layout/breakpoints/expanded.md "Window widths 840dp to 1199dp, such as a tablet or foldable in landscape orientation, or desktop."), like desktop, are modal windows above a scrim. This puts the dialog at the forefront of a person's view, calling attention to the action prompted in the dialog.
Desktop dialogs call attention to the required action
Basic dialogs can be custom-positioned anywhere on larger screens, respecting [margins](../../foundations/layout/layout-overview/overview.md#38a538d7-991f-4c39-8449-195d32caf397 "Margins are the spaces between the edge of a nested element and its parent element, such as the space between a button's label text and the edge of its container.") to prevent edge collision.
Custom placement area for basic dialogs that respects a 56dp margin from the edges of the screen
## Behavior
### Appearing
Dialogs appear without warning, requiring users to stop their current task. They should be used sparingly, as not every choice or setting warrants interruption.
Dialogs use an [enter and exit](../../styles/motion/transitions/transition-patterns.md#e1c2a650-d7a4-4a6d-9025-e6b7845291ed) transition pattern to appear on screen.
A dialog appears with an enter and exit transition
### Position
Dialogs retain focus until dismissed or an action has been taken, such as choosing a setting. They shouldn’t be obscured by other elements or appear partially on screen, with the exception of full-screen dialogs.
Dialogs shouldn’t be obscured by other elements except for full-screen dialogs
### Scrolling
Most dialog content should avoid scrolling. Even when scrolling is required, the dialog title is pinned at the top, with [buttons](../buttons/overview.md "Buttons let people take action and make choices with one tap.") pinned at the bottom. This ensures selected content remains visible alongside the title and buttons, even upon scroll.
Dialogs don’t scroll with elements outside of the dialog, such as the background.
When viewing a scrollable list of options, the dialog title and buttons remain fixed