Intro
The message box (sap.m.MessageBox) is a special dialog that allows you to display messages to the user. Compared to the message popover (sap.m.MessagePopover), you can use the message box to display messages that are not related to a field on the UI, such as technical errors.
When to Use
Do
Use the message box:
- To display messages unrelated to specific UI fields.
- To interrupt users during an action.
- To show error, warning, success, confirmation, or information messages.
- To interrupt users for other reasons.
- To require user acknowledgment of a message.
- To prompt users to make a decision.
Don't
Don’t use the message box:
- If you want to display a brief success message. Use a toast instead. For more information, see Message Toast.
- If the message can be shown directly in a form field.
- Use plain language for messages, avoiding code.
- Clearly describe the issue and suggest a constructive solution.
- Help users recognize, diagnose, and recover from messages.
- Remember that no message is often better than even a well-crafted one. Design your apps to prevent issues from arising in the first place.
Anatomy
The message box contains the following sections and options:
Title: Title text appears in the message box header.
Content: This area contains the actual content of the message box.
Footer with actions: The footer can contain one or more buttons. We recommend limiting the number to two: A primary action and a negative path action.
The message box consists of the following sections and options:
- Title: The title text appears in the header of the message box.
- Content: This section contains the main content of the message box.
- Footer with actions: The footer can contain one or more buttons. We recommend a maximum of two buttons: A primary action and a negative path action.
Example of a message box structure
"Show Details" Button
The message box should generally provide enough information in its short message text for the user to understand what has happened. Therefore, display the Show Details link only if additional information, distinct from the short message text, is important for the user.
If additional details are available, the application can present them in one of three formats:
- Plain
- Formatted
- Original code format
Message details - Plain text
Message details - Formatted text
Message details with code excerpt
Message Types
The available message types are:
- Error
- Warning
- Success
- Information
- Confirmation
Error Message
Trigger error messages when users enter incorrect data or a system error occurs.
These messages should interrupt the user by displaying a dialog. The user must rectify the error before finalizing actions, such as Submit, can be completed.
Control: sap.m.MessageBox
Icon: sap-icon://message-error
Title: Error
Stretch: False (no full screen on any device)
- Don't just describe the problem; provide steps for resolution.
- Speak the end user's language in the short text and avoid system or configuration details.
- If the solution is complex or technical, add a long text.
- Don't repeat the short text in the long text, since both appear on the screen together.
Error message with one action
Error message with two actions
Warning Message
Warning messages draw attention to potential issues while allowing users to proceed. They may include scenarios like unintended data loss.
Control: sap.m.MessageBox
Icon: sap-icon://alert
Title: Warning
Stretch: False (no full screen on any device)
Use Cases for Warnings
a) No decision required
Formulate the message as a statement.
Button(s): OK
Warning message with 'OK' button
b) Decision to continue required
Formulate the message as a statement.
Button(s): OK, Cancel
Warning message with 'OK' and 'Cancel' buttons
c) Specific decision required, with one action
Use the relevant action button. The message can also be formulated as a question.
Button(s): Leave Page, Cancel
Warning message with action and 'Cancel' buttons
Success Message
Success messages provide feedback to the user that an action has been executed. The user needs to acknowledge this message.
Control: sap.m.MessageBox
Icon: sap-icon://message-success
Title: Success
Stretch: False (no full screen on all devices)
Button(s): OK
As a rule, use a message toast (sap.m.MessageToast) to display success messages.
Choose a message box for success messages only in exceptional cases, such as when the message contains key information that users must be able to copy.
Success message
Information Message
Information messages offer details that users need to acknowledge, without requiring a decision. The information is useful and relevant but never critical.
Control: sap.m.MessageBox
Icon: sap-icon://message-information
Title: Information
Stretch: False (no full screen on any device)
Button(s): OK
Information message
Confirmation Message
Confirmation messages ask users to verify an action they have initiated. The message box title includes the action requiring confirmation, such as deletion or approval.
Control: sap.m.MessageBox
Icon: sap-icon://question-mark
Title: <Action> (such as “Approve or “Reject”)
Stretch: False (no full screen on any device)
Button(s): <Action> (such as “Approve” or “Reject”), Cancel
Confirmation message
Confirmation Message with “Note” Section
You can add a "Note" section to confirmation messages, allowing users to include notes (for example, during a "Reject" process).
Since this feature isn’t provided by sap.m.MessageBox, use a standard sap.m.Dialog to add these controls within the confirmation message.
Confirmation message with note
Confirmation for “Delete”
In most cases, deleting an object carries the risk of accidental data loss, which is why the standard delete confirmation dialog uses a warning icon. However, if the delete action isn’t critical, you may opt to use a regular confirmation dialog instead.
Standard "Delete” message box
When the user clicks "Delete," present a "Delete" dialog to confirm the delete action. This dialog combines elements of both warning and confirmation message boxes, using "Delete" as both the title and button label in a warning message box.
Control: sap.m.MessageBox
Icon: sap-icon://alert
Title: Delete
Stretch: False (no full screen on any device)
Button(s): Delete, Cancel
Standard 'Delete' message box
Exception
If the delete action has minimal or no impact, doesn’t result in data loss, and can be easily undone, use a standard confirmation message box with "Delete" as the title and button label.
Control: sap.m.MessageBox
Icon: sap-icon://question-mark
Title: Delete
Stretch: False (no full screen on any device)
Button(s): Delete, Cancel
Example: The user deletes the assignment of an item from the current page, and the item can easily be reassigned later.
Exception of 'Delete' message box
Use Cases
The examples below show use cases for delete confirmation messages in list reports and object pages.
a) No context is available
For example, neither the ID nor the description of the business object is available at the time of deletion.
Body text: Delete this <object>?
Confirmation for 'Delete' action
b) The ID of the object is available
Body text: Delete <object> <object ID>?
Confirmation for 'Delete' action with object ID
c) The object ID and description are both available at the time of deletion
Body text: Delete <object> <object ID> “<object description>”?
Confirmation for 'Delete' action with object ID and description
d) Deleting several objects
If more than one object is being deleted, don’t display the object ID and description.
Body text: Delete the <n = optional> selected <objects>?
Confirmation for 'Delete' action with several objects
Responsive Behavior
The sap.m.MessageBox control has the same responsive behavior as the sap.m.Dialog control. The message box should only be opened in modal mode. Its basic width is 25 rem. For more information, see Dialog.
Related Links
Elements and Controls
- Message Handling (guidelines)
- Message Popover (guidelines)
- Dialog (guidelines)
Implementation
- Message Box (SAPUI5 samples)
- Message Box (SAPUI5 API reference)
Visual Design
- Message box (visual design specification)
Elements and Controls
- Message Handling (guidelines)
- Message Popover (guidelines)
- Dialog (guidelines)
Implementation
- Message Box (SAPUI5 samples)
- Message Box (SAPUI5 API reference)