Updated: February 8, 2023

Dialog

sap.m.Dialog

Intro

The dialog control (sap.m.Dialog) interrupts the current app process to prompt the user for information or for a response. It forces a decision or a confirmation that needs to be signed off by the user.

Usage

Use the dialog if:

  • You want to display complex content (that is not a floorplan), but don’t want the user to navigate away from the current page.
  • You want to display an additional step or process that needs to be confirmed by a user action.
  • You want to enable the user to create an object with a small number of fields (up to 8 fields).

Do not use the dialog if:

  • You want to display a simple message. Use the message box instead.
  • You just want to confirm a successful action.
  • You do not want to interrupt the user.
  • You want to enable users to create an object with more than 8 fields. Use an object page instead.
  • You want to display a floorplan. Floorplans are not meant to be displayed inside a dialog.

Responsiveness

The dialog provides different behavior on a smartphone than on a tablet or desktop. We distinguish between “cozy” and “compact” dialogs. For more information, see content density.

The buttons in the toolbar are aligned differently on the various devices. On a smartphone, they extend across the entire footer toolbar, but on a tablet or desktop device, they are right-aligned.

Size S (Smartphone)

Full Screen Dialog

We recommend displaying dialogs in S size in full screen mode to help users focus on the content of the dialog (property stretch = “true”). The toolbar containing the actions is positioned at the bottom of the dialog.

Position of the Action Buttons

On smartphones, a dialog can have one or two actions, which are located in the footer and right-aligned.

Full screen dialog - Size S
Full screen dialog - Size S

When to Open Full Screen or Modal

Always display message dialogs as modals. There is no need to display a simple message in a full screen dialog. If you want to display a simple message, use the message box instead.

If you use standard dialogs, such as value help, open them in full screen mode to help the user can focus on the content of the message. The dialog control offers a stretch property for full screen behavior.

Size M (Tablet)

By default, the dialog can have up to two action buttons in the footer. The action buttons in the toolbar are right-aligned. Use cozy mode on tablet devices.

If the content height increases or is set to more than the screen height, the dialog height stops at 4 rem from the top and bottom. The user can then scroll through the content area.

Size L (Desktop)

By default, the dialog can have one or two actions. The action buttons on a desktop device are right-aligned. Use compact mode to ensure that the padding and margins are optimized for desktop devices.

If the content height increases or is set to more than the screen height, the dialog height stops at 4 rem from the top and bottom. The user can then scroll through the content area.

Dialog in compact mode - Size L
Dialog in compact mode - Size L

Layout

Position on the Screen

The dialog is positioned in the center of the screen. It opens in a modal window to ensure that it attracts the user’s attention when it displays emergency states.

On a smartphone, the stretch property allows you to achieve full screen behavior.

Behavior and Interaction

Navigation in a Dialog

You can let users navigate to another page within the dialog. On the second page, an arrow at the top of the dialog allows users to navigate back to the first page.

Navigation pattern list - Size L
Navigation pattern list - Size L
Navigation pattern details - Size L
Navigation pattern details - Size L

 

Resizable

You can let users change the size of the dialog (property resizable = “true). The resizable indicator then shows in the bottom-right corner of the dialog.

Resizable indicator in the bottom right-hand corner - Size L
Resizable indicator in the bottom right-hand corner - Size L

Draggable

By clicking and holding on the heading, users can drag the dialog to another position (property draggable = “true”).

Dialog can be moved by dragging the title - Size L
Dialog can be moved by dragging the title - Size L

 

Messaging Within a Dialog

If your dialog contains a scrollable form, use a message popover to help visualize any issues that are hidden when scrolling.

Warning
Don’t use a message popover in small dialogs where the popover might obscure form fields that are in focus.
DIalog with message popover
DIalog with message popover

 

Editing and Saving Content

If a dialog is used for editing, keep it simple. If you need more than 8 editable fields, consider other solutions instead, such as navigation to a details page.

The data in the dialog is only saved when the user clicks Create or Save. Use form field validation within the dialog to make users aware of any errors.

The data in the dialog is lost if the page is refreshed during the editing process (also in the draft scenario), or if the user chooses Cancel.

Highlighted form fields in a dialog - Size S
Highlighted form fields in a dialog - Size S

 

Types

Standard Dialog

Use the standard dialog unless you need one of the specialized dialogs below. The standard dialog has a header with a grey background, and no icon.

Message Box

The message box is a special type of dialog that is used to display messages quickly. For each type of message, you can decide when to use a dialog. Use the message toast (sap.m.MessageToast) for success messages. For more information, see Message Box.

Components

The dialog contains the following sections and options:

Title: The title text appears in the dialog header. By default, the title is left aligned.

Subheader (optional): Subheaders appear below the main header. Since the subheader is not part of the content area, it is not scrollable.

Content: This area contains the actual content of the dialog.

Footer with actions: The footer can contain up to two buttons (optional). If no buttons are defined, the default Close button is shown.

Example of a dialog structure (Cozy)
Example of a dialog structure (Cozy)

Emphasized Buttons in a Dialog

Always use an emphasized button for the the standard action. Emphasizing the main action in the dialog toolbar helps users to focus on the most likely choice. This saves users time and gives new users a sense of orientation.

Never use an emphasized button for Cancel.

Emphasized button in the dialog footer
Emphasized button in the dialog footer

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation