UI Elements - SAPUI5 Loading / Processing Busy Dialog

Updated: February 22, 2023
Latest Version 1.128

Busy Dialog

sap.m.BusyDialog

Intro

The busy dialog informs the user about an ongoing operation. During the operation, the entire screen is blocked.

Usage

Use the busy dialog if:

  • The user should not be able to start any other activity during an operation, and the screen needs to be blocked while the operation is ongoing.
  • The operation lasts more than one second.
  • You want to indicate loading in a page-to-page navigation.

Do not use the busy dialog if:

  • The operation lasts less than one second.
  • The screen is not supposed to be blocked. In this case, use the busy indicator or busy state of the control instead.

Responsiveness

The busy dialog is fully responsive and can be shown in compact and cozy mode.

Busy dialog - Compact mode
Busy dialog - Compact mode
Busy dialog - Cozy mode
Busy dialog - Cozy mode
Busy dialog on smartphone
Busy dialog on smartphone
Developer Hint
To switch to compact mode for a dialog, you need to use:

jQuery.sap.syncStyleClass(“sapUiSizeCompact”, this.getView(), this._oDialog);

For more information, see the SAPUI5 Demo Kit.

Components

The busy dialog can consist of several components and is configurable. The following properties can be set:

  • Title: By default, it has no title. Define a title if you need to provide more context.
  • Text: Additional text can be added above the busy animation.
  • Cancel:(Property:showCancelButton) A Cancel button is displayed. There is no Cancel button by default. The label is also configurable via Property.cancelButtonText.
  • Icon: A custom animation icon can be set via Property:customIcon.

If no title, text, or Cancel button is set, the busy dialog displays only the busy icon (busy dialog, lightweight version).

Busy dialog with 'Cancel' button
Busy dialog with 'Cancel' button
Busy dialog without 'Cancel' button
Busy dialog without 'Cancel' button
Busy dialog - Lightweight version
Busy dialog - Lightweight version

Guidelines

Lightweight Version (No Title, Text, or Cancel Button)

  • Use the lightweight version for page navigation (see live example).

  • If you do not show a title or text, use the invisible text control (sap.ui.core.InvisibleText) to provide the reason for the busy state to users with assistive technologies.

Developer Hint

The additional text should be associated to the busy dialog using ariaLabelledBy association.

Busy Dialog with Text

  • Do not use the title of the busy dialog.
  • If a busy dialog is triggered directly by the user, provide a precise text describing the operation. The text can be as short as one verb:
    • Loading…
    • Refreshing…
    • Sending…
  • If the busy dialog is not directly initiated by the end user, use at least one sentence to describe the operation. Start either the first or the last sentence with Please wait. For example: The system is busy searching data. Please wait until data is loaded.

  • Recommendation: Do not use the invisible text control when you show text in the busy dialog.

Busy Dialog with Text and Cancel Button

  • Offer Cancel if you expect the process to run more than 10 seconds. In addition, always display text that precisely describes the ongoing operation.
  • Do not change the mouse cursor to indicate the ongoing operation.
  • Recommendation: Do not use the invisible text control when you show text in the busy dialog.

Timing and Duration

We recommend displaying the busy dialog one second after the process has been triggered and for a minimum time of 500 ms to avoid flickering. For processes that last less then one second, a busy dialog is not displayed at all.

Example: A process takes 1.3 s in total. After one second, the busy dialog is displayed. The process finishes in 1.3 seconds. To avoid flickering, you should display the busy dialog for at least 500 ms, so you will need to add 200 ms to avoid flickering.

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