Guidelines
When to use
- Immediate action: When an immediate response from the user is required to proceed.
- Confirmation: To confirm user decisions, especially for destructive or irreversible actions, like deleting an item.
- Acknowledgment: To inform users about relevant information.
- Input: To request users additional information or make a selection before proceeding.
When not to use
- Non-critical information: Don't use Dialogs for non-critical information or minor notifications. Instead, use an Alert, which can be dismissed or disappear automatically.
- Multi-step tasks: Avoid interrupting multi-step tasks with Dialogs or using a sequence of Dialogs. Choose a Progress Indicator instead.
- Extensive content: If the content to be displayed is extensive, consider using a separate page or a Side Panel rather than a Dialog, which may feel cramped and overwhelming.
- Nesting: Show only one Overlay or Dialog at a time. The only exception is when confirming a destructive action over a Floating Panel.
Dialog vs. Alert
Understanding the difference between Dialog and Alert components will help you select the appropriate one for effectively communicating with users.
- Dialogs: Dialogs are overlays that interrupt the current workflow and remain on the screen until the user takes action. Use them when immediate action is required or to display critical messages.
- Alert: Alerts present feedback in a non-disruptive way and disappear automatically without interrupting the workflow. Use them to display less critical information.
Don't use Dialogs for non-critical information, such as simple success notifications.
Use an Alert notification to display feedback on simple, successful actions.
Best Practices
- Use Dialogs cautiously, ensuring clear benefits for the user, like drawing focus on a task or making important decisions.
- Keep Dialog tasks short and simple.
- Always provide a clear method for dismissing a Dialog.
- Use clear titles and messages to ensure context clarity.
- Use one Dialog at a time, avoiding clutter and confusion.
- Avoid using more than two footer action buttons.
Position
Dialogs are strategically placed to optimize user experience based on context.
|
Position |
Usage |
|---|---|
|
Center |
Used on most Dialogs, ensuring focus on the content. |
|
Corner (bottom right) |
Ideal for non-modal Dialogs that require visibility of the main page content. |
Behaviors
Dismissing/closing
Users can only interact with the main page once the Dialog is closed. We provide several options to ensure they can quickly dismiss a Dialog when needed.
- Click/tap the Close Button.
- Click/tap the Overlay (in non-critical scenarios)
- Click/tap the Dismissing Button (if applicable).
Trigger
Dialogs are always activated by a user action and are never system-generated. The primary trigger is typically a Button, but they can also be triggered by other interactive components. Additionally, pressing Enter or Space on a keyboard should also activate them.
Confirmation
After completing an action, it's recommended to show an Alert to confirm a successful operation. Please refer to the Error messaging guidelines for error messages and validation guidance.
Overflow content
The content scrolls when the Dialog exceeds a certain height, while the header and actions container stay fixed.
Modal Dialogs prevent the main page from scrolling until the user takes action to complete the task or dismiss it.
Layout
Mobile vs. Desktop
Dialogs will adapt their layout on small screens, such as mobile devices, to improve usability.
- The Close Icon Button increases to Medium size for easier selection when tapping.
- Text Buttons increase to Extra Large size for easier selection when tapping.
- Buttons align vertically and use the full width of the container.
On Mobile
• Change button size to improve selection when tapping.
• Align buttons vertically.
• Don't keep buttons aligned in a row.
• Don't set buttons to auto-width.
On Desktop
• Set the buttons to auto width.
• Don't set the buttons to full width.
Footer
The Dialog footer consists of two slots, usually filled with Buttons for confirming, dismissing, or acknowledging something. While you can add custom content, we offer pre-filled options to help you create the composition and follow our button order and hierarchy, as follows:
- Confirming actions (primary and secondary buttons): place them at the end of a row (Desktop) or at the top of a stack (Mobile).
- Dismissing action (tertiary button): place it at the beginning of a row (Desktop) or the end of a stack (Mobile), separated from confirming actions. Make sure to use the tertiary variant.
Align actions based on our button hierarchy patterns.
Don't rearrange the action order inconsistently, as it can confuse users.
Content
General principles
Make the action and its consequences clear and scannable. Users should be able to glance at the title and the button, and understand what they are doing.
- The title should be 2 or 3 words clearly stating the reason for the dialog.
- The body should provide more detailed information, including any consequences of the action.
- The button should reaffirm the action they are taking.
Do not overload with layers or visual complexity
If you need several layers to communicate or highlight everything, consider using other components.
Title
Make the title clear and specific
It should describe what the dialog is about.
✅ Cancel booking
✅ Delete rate?
🚫 Warning! / Form
🚫 Confirmation
🚫 Are you sure?
Keep it short (1 line)
Do not use long, full sentences in the title.
✅ Delete rate group?
🚫 Are you sure you want to delete the rate group?
✅ Verify email
🚫 You’ll need to verify your email
Use sentence case and no period
Only use punctuation if the title is a question.
✅ Delete booking?
✅ Verify email
🚫 Verify your email.
Body
Adjust tone and length to the situation
When helping the user complete an action, keep it short and simple.
When action is required, avoid long, conversational messages.
When simply communicating a problem (especially in guest-facing messages), be more conversational and polite.
Buttons