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

Usage

Use the dialog if:

• You want to display a system message.
• You want to interrupt the user’s action.
• You want to show a message with a short and a long description.

Do not use the dialog if:

• You just want to confirm a successful action.
• You do not want to interrupt the user’s action.

Responsiveness

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

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

Size S (Smartphone)

Full Screen Dialog

We recommend displaying dialogs in S size in full screen mode. Most of the content of a dialog is worth opening in full screen so the user is able to focus on the content of the dialog. The stretch property can be easily set by the application to true. The toolbar on which the actions are placed within a dialog is positioned at the bottom of the dialog.

Position of the Action Buttons

By default, the dialog can have one or two actions, which cover the entire footer on smartphones.

When to Open Full Screen or Modal

Message dialogs should always be displayed 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 (sap.m.Messagebox) instead.

If you use standard dialogs such as value help, you should open them in full screen mode. The device’s entire screen is used to display the dialog, and the user can focus on the content of the message. The dialogs offer 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.

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

Resizable

The user can change the size of the dialog by setting the “resizable” property to true. The following figure shows the resizing indicator, which helps the user to identify this functionality.

Draggable

Dialogs can be moved by dragging the header to another position. Set the property “draggable” to ‘true’ and by clicking the title the user can move the dialog to another position.

Messaging in Dialog

Message popovers do not need to be displayed in the dialogs. Keep it simple and just highlight each field that has a problem. For more information, see form field validation.

Types

Standard Dialog

Use the standard dialog if you want to display a common dialog. The main visual differences are that the header is displayed with a grey background, and that no icon is shown.

The content can be filled with your application-specific data.

Other Types of Dialog

• Personalization dialog
• Select dialog
• Table select dialog
• Value help dialog
• View settings dialog
• Busy dialog

Message Box

The message box is a special type of dialog that is used to display messages quickly. For each type of message, the app team 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: Title text appears in the dialog header.

Subheader: When a subheader is assigned to a dialog (optionally), it appears below the main header. As 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 (optionally).

Resources

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