Waldo sessions now support scripting! – Learn more
App Development

How to Use MBProgressHUD in Swift: A Guide

Juan Reyes
Juan Reyes
How to Use MBProgressHUD in Swift: A Guide
January 31, 2023
min read

One of the most overlooked elements of standard mobile UI designs is the progress indicator, or HUD. This UI element is one of the most ubiquitous non-Apple UI elements in the market, and chances are that if you're not an experienced iOS developer, you didn't know it wasn't a standard UI element that comes built in.

The most popular progress indicator available is known as MBProgressHUD, and you can find it in a large portion of the iOS applications available in the app store.

MBProgressHUD is a popular open-source library for displaying progress indicators on iOS and macOS applications. It's easy to use and provides a simple way to show progress or activity to the user.

In this post, I'll introduce you to MBProgressHUD.

I'll first show you how to install it in your project. Then, I'll show you how to use it by displaying a simple progress indicator. Finally, I'll walk you through how to customize it and implement some advanced behavior.

If you don't have any experience working with Swift or Xcode, you should take your time to learn a bit more first.

There, you can familiarize yourself with Swift's UI design and programming basics.

Let's jump right in.

Introduction to MBProgressHUD

As mentioned above, MBProgressHUD is a simple but robust library for displaying progress indicators on iOS and macOS applications. It was created by a developer named Matej Bukovinski and is widely used by developers in their projects.

The library is written in Objective-C but can easily be used in Swift projects through bridging headers.

MBProgressHUD provides a simple and easy-to-use interface for showing progress or activity to the user. You can use it to display a spinning activity indicator, a progress bar, or a custom view. The library also provides options for customizing the appearance and behavior of the progress indicator, such as the background color, the font, and the animation duration.


MBProgressHUD works on iOS 9.0+. It depends on the following Apple frameworks, which should already be included with most Xcode templates:

  • Foundation.framework
  • UIKit.framework
  • CoreGraphics.framework

You'll need the latest developer tools in order to build MBProgressHUD. Old Xcode versions might work, but compatibility will not be explicitly maintained.

Installing MBProgressHUD

You have several options to use MBProgressHUD in your Swift project.

XCode Swift Package Manager

Go to Files > Add package and add the HUD package with the following URL:



CocoaPods is a dependency manager for iOS and macOS projects. To install MBProgressHUD using CocoaPods, add the following line to your Podfile:

$ pod 'MBProgressHUD'

Then, run the pod install command to install the library.


Carthage is another dependency manager for iOS and macOS projects. To install MBProgressHUD using Carthage, add the following line to your Cartfile:

github "matej/MBProgressHUD"

Then, run the Carthage update command to build and install the library.

Manual Installation

Alternatively, you can manually install MBProgressHUD by downloading the source code from the GitHub repository and adding the files to your project.

Source Files

Furthermore, you can directly add the MBProgressHUD.h and MBProgressHUD.m source files to your project.

  1. Download the latest code version or add the repository as a Git submodule to your Git-tracked project.
  2. Open your project in Xcode. Then, drag and drop MBProgressHUD.h and MBProgressHUD.m onto your project (use the "Product Navigator view"). Select Copy items when asked if you extracted the code archive outside your project.
  3. Include MBProgressHUD wherever you need it with #import "MBProgressHUD.h".

Static Library

You can also add MBProgressHUD as a static library to your project or workspace.

  1. Download the latest code version or add the repository as a Git submodule to your Git-tracked project.
  2. Open your project in Xcode, then drag and drop MBProgressHUD.xcodeproj onto your project or workspace (use the "Product Navigator view").
  3. Select your target and go to the Build phases tab. In the Link Binary With Libraries section, select the Add button. On the sheet, find and add libMBProgressHUD.a. You might also need to add MBProgressHUD to the Target Dependencies list.
  4. Include MBProgressHUD wherever you need it with #import <MBProgressHUD/MBProgressHUD.h>.

Displaying a Progress Indicator

To display a progress indicator using MBProgressHUD, you need to import the library and create an instance of MBProgressHUD. You can do this in the view controller, where you want to show the progress indicator.

import MBProgressHUD

class ViewController: UIViewController {
    var hud: MBProgressHUD!

    override func viewDidLoad() {

        hud = MBProgressHUD.showAdded(to: view, animated: true)

The showAdded(to:animated:) method adds the progress indicator to the specified view and starts the animation. You can also use the show(animated:) method to show the progress indicator on the current view.

By default, the progress indicator will show a spinning activity indicator. However, you can customize the progress indicator's appearance and behavior using the library's various properties and methods.

For example, you can change the label text and the details label text using the label.text and detailsLabel.text properties, respectively. You can also change the labels' font and color using the label.font and label.color properties.

Further, you can change the background color and the animation style of the progress indicator using the bezelView.color and animationType properties, respectively.

The bezelView.color property controls the color of the background view, and the animationType property controls the type of animation used to show and hide the progress indicator.

hud.bezelView.color = .white
hud.animationType = .fade

In addition to the spinning activity indicator, MBProgressHUD also supports displaying a progress bar. To show a progress bar, you can use the mode property and set it to .determinate. You can then update the progress using the progress property.

hud.mode = .determinate
hud.progress = 0.5

Finally, you can also show a custom view instead of the default progress indicator. To do this, you can use the customView property and set it to the view you want to display.

let imageView = UIImageView(image: UIImage(named: "custom"))
hud.customView = imageView

Hiding the Progress Indicator

You can use the hide(animated:) method to hide the progress indicator. This will stop the animation and remove the progress indicator from the view.

hud.hide(animated: true)

You can also use the hide(animated:afterDelay:) method to hide the progress indicator after a specific delay.

hud.hide(animated: true, afterDelay: 2)

Advanced Usage

MBProgressHUD provides several advanced features that you can use further to customize the appearance and behavior of the progress indicator.

For example, you can use the margin property to control the margin between the progress indicator and the edges of the view. You can also use the minSize property to set the minimum size of the progress indicator.

hud.margin = 20
hud.minSize = CGSize(width: 200, height: 100)

Additionally, you can use the graceTime and minShowTime properties to control the minimum and maximum duration of the progress indicator.

The graceTime property controls the amount of time that the library will show the progress indicator before the actual task starts. The minShowTime property controls the minimum amount of time that the progress indicator will be shown, even if the task finishes before that time.

hud.graceTime = 0.5
hud.minShowTime = 1

Finally, you can use the completionBlock property to specify a block of code to be executed when the progress indicator is hidden. This can be useful for performing cleanup tasks or displaying a message to the user after completing the task.

hud.completionBlock = {
    print("Progress indicator hidden")

Moving on

This post taught us how to use MBProgressHUD to display progress indicators in Swift applications. I covered the basics of installing and showing the progress indicator and some advanced features for customizing the appearance and behavior.

MBProgressHUD is a simple and easy-to-use library that can help improve the user experience of your iOS and macOS applications.

Now, if you want to make sure your code is working as expected, give Waldo's extensive toolbox for UI testing a look if you want to be sure your code is reliable and safe. Even nondevelopers may use it easily because it doesn't require any code.

Automated E2E tests for your mobile app

Waldo provides the best-in-class runtime for all your mobile testing needs.
Get true E2E testing in minutes, not months.

Reproduce, capture, and share bugs fast!

Waldo Sessions helps mobile teams reproduce bugs, while compiling detailed bug reports in real time.