Intro

The dialog control (sap.m.Dialog) pauses the current app flow to collect a response or decision from the user. It requires explicit input – such as confirmation, cancellation, or data entry – before proceeding.

Dialog

When to Use

Anatomy

Dialog anatomy

1. Header: Contains the title of the dialog.
2. Content: Can contain any component.
3. Resize handle (optional): If enabled, the resize handle lets users stretch and shrink the dialog. The resize handle is only available on desktop devices.
4. Footer: Can contain actions that affect the entire dialog. The action buttons are right aligned.
5. Subheader (optional): Appears below the main header. Since the subheader is not part of the content area, it is not scrollable.

Position on the Screen

The dialog is positioned at 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.

You can use the stretch property to show the dialog in full screen mode on smartphones.

Types

Standard Dialog

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

Standard dialog

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. For success messages, use the message toast (sap.m.MessageToast). For more information, see Message Box.

Other Types of Dialog

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

Behavior and Interaction

The dialog opens in a modal window at the center of the screen. Completing an action or closing the dialog returns the user to the main screen.

Actions in the Footer

By default, the dialog footer contains one or two actions. Depending on the specific use case, more actions are also allowed.

Always use an emphasized button for the primary action in the footer. The dialog footer can have only one primary action.

If the footer contains a single action with a negative path, such as Close, use a transparent button. Negative paths navigate away from the dialog without executing any actions.

Navigation in a Dialog

Dialogs can support navigation between internal views within the same pop-up. Users can move from a primary to a secondary screen inside the dialog. A back arrow at the top lets users return to the previous view without leaving the dialog.

Resizable

The dialog can be made resizable by setting the resizable property to “true”. When enabled, a resize handle appears in the bottom-right corner, allowing users to adjust the dialog size.

Resizable indicator in the bottom right-hand corner

Draggable

Users can reposition the dialog by clicking and dragging its header. This behavior is enabled by setting the draggable property to “true”.

Draggable indicator in the header

Messaging Within a Dialog

When a dialog contains a scrollable form, use a message popover to surface any messages that may otherwise be hidden during scrolling.

Dialog with message popover

Editing and Saving Content

If a dialog is used for editing, keep it simple. If you need a large number of 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

Emphasized Buttons in a Dialog

Always use an emphasized button for the primary 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. If the footer contains a single action with a negative path, such as Close, use a transparent button. Negative paths navigate away from the dialog without executing any actions.

Emphasized button in the dialog footer

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.

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.

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)

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)

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.

Localization

The dialog component supports both left-to-right (LTR) and right-to-left (RTL) languages. In left-to-right contexts, content is left-aligned and action buttons (OK and Cancel) are placed on the right. In right-to-left contexts, text is right-aligned and buttons appear on the left.

Related Links