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 complex content but don’t want the user to navigate away from the current page.
• You want to display an additional step or process on the UI, which the user has to confirm via an action at the end.
• You want 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’s action.
• You want to create an object with more than 8 fields. Use an object page instead (sap.m.ObjectPage).

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.

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 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 “draggable” property  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 dialogs. For example, to show an issue with with content in a field, highlighting can be used. 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 Dialogs

• 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

Emphasized Buttons in a Dialog

By emphasizing a button in the dialog toolbar, the user can focus more on the action that the application would see as the standard action. Use an emphasized button if you want to better guide your user.

Resources

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