Implementation references

Scripting API and implementation references.

UI Toolkit
IMGUI
Other

Progress bar · UX essentials

Key guidance on progress bar component.

Progress bar control shows the progress between a user set upper and lower value.
Blue plus sign icon indicating that clicking on this will expand this content
Use EditorUtility.DisplayProgressBar for blocking operations.
Blue plus sign icon indicating that clicking on this will expand this content
Use Progress utility class for background operations.
Blue plus sign icon indicating that clicking on this will expand this content

Resources and API documentation

Overview

Progress bar control used to display depth of field adjustments, between a minimum and maximum values.

A progress bar is a display component that shows the progress status of an operation. The progress bar fills between a lower and upper bound value as the operation continues.

  • Progress bars display the operation linearly,
  • Used for determined duration actions to display the progress,
  • They should be used when the process completion rate can be detected,
  • Progress bars inside a container, can indicate the process applies to that particular container, and that interaction with the rest of the Editor is possible

Progress bar APIs

Progress bar in UI Toolkit

Object field UI Builder icon
UI Builder allows visual creation of UI assets in UI Toolkit, and is available as a built-in feature {2021.1 and later} or a package {2020.3 and earlier}
UI Toolkit
Progress Bar in IMGUI
IMGUI

Displaying operations

Blocking operations

The Background Tasks window displays the progress of any running asynchronous tasks.

The EditorUtility.DisplayProgressBar utility class displays or updates a native progress dialog for long operations that make the editor non-responsive.

This is useful when you perform a long blocking operation in an Editor script, and want to notify the user about the progress. Use this method for long operations that make the editor non-responsive such as; importing / reimporting / refreshing assets.

Classes

Background Operations

The Background Tasks window displays the progress of any running asynchronous tasks.

The Progress utility class reports the progress of asynchronous tasks to the Unity Editor, to be displayed in the background tasks window. It is best used for long operations that happen in the background.

Classes

Guidance

When To Use

  • Use progress bars to show linear operations with a determined upper value,
  • Use progress bars in the interface after the control that initiates or adjusts it,
  • When displaying progress for a sequence of tasks, use a single progress bar for the overall progress rather than each activity.

Persistency

Progress bar controls can be displayed persistently where the operation is repeated, and the user has a manual option to remove / clear progresses, or they can be displayed temporarily in the interface the operation takes place and can be hidden after the operation is complete.

For displaying operations that don't need to be displayed in the Editor interface, see displaying operations.

Custom loaders

Loading animations are frequently used whenever a user has requested an action that will take an extended period of time. There are accessibility challenges to consider when choosing what type of loader to use. If they are built incorrectly they can create confusion and frustration for users.

It’s important to use the correct animation for the job.

  • Is there associated progress data? Use a progress indicator that shows the time or percentage of completion.
  • Is there no associated progress data? Use a standard circle loader to depict infinite loading.
  • Does the process lack progress data? Avoid using a progress indicator or a visual design similar to a progress indicator for an infinite load with no associated progress data. Improperly using progress indicators creates special difficulties for those people with cognitive disabilities while generally causing frustration and annoyance for all users.

Formatting

Placement

  • Progress bars should be placed after the control that initiates or adjusts it,
  • Progress bars should be in the same interface view where the operation takes place,
  • Progress bars inside a container, can indicate the process applies to that particular container, and that interaction with the rest of the Editor is possible,