Updated: March 17, 2021

Progress Indicator

sap.m.ProgressIndicator

Intro

The progress indicator visualizes the current advancement of a process or a degree of accomplishment. The inside of the progress indicator is filled with color to indicate the state of progress. The advancement depends on the specific process. The progress is shown either using absolute numbers or the current percentage of completion together with a progress bar.

Within SAP Fiori, the progress indicator is used as a “meter” or micro chart. It indicates a current object status and is not related to any process that is currently running.

Usage

Use the progress indicator if:

  • You need to visually show a current status.
  • You need to visually strengthen a current status.
  • You need to make different states comparable to each other at a higher level.
  • You want to show custom values as well as percentages.

Do not use the progress indicator if:

  • Visual feedback is needed for an ongoing operation. Use a busy indicator instead.
  • The progress is indeterminate. Use a busy indicator instead.
  • You want to display a single value in the form of a fillable shape or a group of shapes that describe their context. Use the status indicator instead.

Responsiveness

The progress indicator itself is not responsive. It supports the cozy and compact form factors. The compact form factor is used for apps that run on a device operated by a mouse and keyboard. For more information, see Content Density (Cozy and Compact).

Progress indicator in compact mode
Progress indicator in compact mode
Progress indicator in cozy mode
Progress indicator in cozy mode

Layout

Show the current progress as a percentage value between 0% and 100%. Property: percentValue.

Progress indicator displaying 10% progress
Progress indicator displaying 10% progress
Progress indicator displaying 50% progress
Progress indicator displaying 50% progress
Progress indicator displaying 80% progress
Progress indicator displaying 80% progress

Alternatively, you can show the current progress as text in addition to the bar. In this case, the text is shown on the right of the bar if the progress is 50% or less. In all other cases, the progress is shown right-aligned on the bar itself. Property: showValue.

Textual presentation for progress of 50% or less
Textual presentation for progress of 50% or less
Textual presentation for progress of more than 50%
Textual presentation for progress of more than 50%
Progress indicator without textual representation
Progress indicator without textual representation

You also have the option of showing any application-specific text instead of a percentage. Property: displayValue.

App-specific textual representation of progress
App-specific textual representation of progress

Styles

The progress indicator can be enabled or disabled. Property: enabled.

Enabled progress indicator
Enabled progress indicator
Disabled progress indicator
Disabled progress indicator

For usage in read-only forms or read-only tables, the progress indicator provides a “display” state. This state is optimized for reading environments. The default height is lower, and the bar color darker. Property: displayOnly.

Progress indicator in display state
Progress indicator in display state

The progress indicator can visualize different value states that are represented by various theme-dependent semantic colors. The states are: normal, success, warning, and error. Property: state.

Value states can be combined with the “enabled” and “display” states.

Progress indicator in success state
Progress indicator in success state
Progress indicator in warning state
Progress indicator in warning state
Progress indicator in error state
Progress indicator in error state

Guidelines

Use the progress indicator to add clarity and weight to an important state that needs to be perceived very quickly.

Progress indicator used for status display
Progress indicator used for status display

Always provide a label for the progress indicator.

Exception: If the progress indicator is used as a single control inside a cell of a responsive table, the column header text is used as a label.

Progress indicator in a responsive table
Progress indicator in a responsive table

Use a group of up to five bars to help users compare different states at a high level. Note that in a group of more than five bars, slight differences are much harder to perceive than a numeric display.

If the user has to compare a group of values, be sure to use the same visual display for all of them (only bars or only numbers).

Group of progress indicators
Group of progress indicators

Progress indicators are typically used within (but not restricted to) the following controls:

Do not disable a progress indicator. A progress indicator is not interactive, therefore disabling it has no effect.

Exception: The progress indicator is shown inside a disabled UI area, such as a completely disabled form or panel.

Properties

The following additional properties are available for the progress indicator:

  • The property “width” defines the width of the progress indicator. The property “height” defines the height of the progress indicator. Adapt it only if the default height does not fit into the surrounding context. Do not use a height below 1.5 rems if text is shown inside the progress indicator.
  • The property “textDirection” is used for localiaztion (right-to-left languages).
  • The property “busy” sets the progress indicator to busy state.
  • The property “visible” shows or hides the progress indicator.
  • The property “tooltip” does not have an effect.

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