How to Customize MBProgressHUD

MBProgressHUD looks clean out of the box, but it does not have to look the same in every app. You can change the text, the fonts, the colors, the background, the animation, and the timing. A few small changes can make the HUD match your app’s design, so it feels like part of your app instead of a generic add-on. This guide shows you the most useful customization options, with the exact code for Swift and Objective-C.

Before you start, make sure MBProgressHUD is installed and imported in your view controller. The install guides in this series cover Swift Package Manager, CocoaPods, and the other methods. The library requires iOS 9.0 or later and ARC. Most customization happens right after you create the HUD and before you show it, or right after you show it. The code in this guide works in both Swift and Objective-C.

Change the Label and Details Label

The label and details label are the two text lines on the HUD. The label is the main line, and the details label is the smaller line below it. You can set both with simple assignments. In Swift, write hud.label.text = “Loading” and hud.detailsLabel.text = “Fetching your data”. In Objective-C, write hud.label.text = @”Loading” and hud.detailsLabel.text = @”Fetching your data”.

You can also change the fonts. In Swift, write hud.label.font = UIFont.boldSystemFont(ofSize: 16) to make the label bold, or hud.detailsLabel.font = UIFont.systemFont(ofSize: 13) to make the details smaller. In Objective-C, write hud.label.font = [UIFont boldSystemFontOfSize:16] and hud.detailsLabel.font = [UIFont systemFontOfSize:13]. Keep the fonts readable and consistent with the rest of your app. A HUD that uses a wild font will look out of place.

Change the Colors

You can change the color of the label text and the background. In Swift, write hud.contentColor = UIColor.white to make the text and the spinner white, which works well on a dark background. In Objective-C, write hud.contentColor = [UIColor whiteColor]. The content color affects the label, the details label, and the indicator, so one line changes the whole look.

You can also change the background color of the HUD itself. The HUD has a bezel view, which is the rounded box that holds the indicator and the text. In Swift, write hud.bezelView.color = UIColor.black, or set hud.bezelView.style to change the shape. In Objective-C, write hud.bezelView.color = [UIColor blackColor]. A dark bezel with white text is a classic look, and it works well on light screens.

Change the Background Dimming

By default, MBProgressHUD dims the screen behind the HUD slightly, which tells the user the app is busy. You can change how strong that dimming is. The HUD has a background view that covers the whole screen, and you can set its color and its opacity. In Swift, write hud.backgroundView.color = UIColor.black.withAlphaComponent(0.3) for a light dim, or use a higher alpha for a stronger dim. In Objective-C, write hud.backgroundView.color = [[UIColor blackColor] colorWithAlphaComponent:0.3].

You can also turn the dimming off completely by setting the background view color to clear. That makes the HUD float over your interface without dimming anything. It looks lighter, but the user may not realize the app is busy, so use it only when the task is very short.

Change the Animation

MBProgressHUD can fade in and out, or it can zoom in and out. The default is a fade, which looks smooth and calm. You can change it by setting the animation type. In Swift, write hud.animationType = .zoom to make the HUD scale up as it appears. In Objective-C, write hud.animationType = MBProgressHUDAnimationZoom. The zoom animation feels more playful, and it works well in apps with a light tone.

You can also change how long the animation takes, though the default duration is fine for most apps. If you want a slower, more dramatic entrance, you can set a longer duration, but be careful. A slow animation on a HUD that appears often will feel sluggish, and the user will notice the delay.

Control the Timing

Two timing settings make the HUD feel smooth. The grace time delays the HUD by a short time, so fast tasks never show it at all. In Swift, write hud.graceTime = 0.5. In Objective-C, write hud.graceTime = 0.5. The minimum show time keeps the HUD visible for a minimum time, so it does not flash and vanish. In Swift, write hud.minShowTime = 1.0. In Objective-C, write hud.minShowTime = 1.0.

You can also change the margin, which is the space between the HUD content and the edge of the bezel. In Swift, write hud.margin = 20.0 to add more space, or a smaller value to make the HUD tighter. In Objective-C, write hud.margin = 20.0. A larger margin makes the HUD feel roomy, and a smaller margin makes it feel compact.

Remove the HUD Automatically

By default, MBProgressHUD removes itself from its superview when you hide it. That setting is called removeFromSuperViewOnHide, and it is true by default. You can leave it alone in most cases. If you set it to false, the HUD stays in the view hierarchy after you hide it, and you can show it again later without creating a new one. That is useful if you show the same HUD many times in one screen, but it also means you must manage the HUD yourself, so most developers leave the default.

Match the HUD to Dark Mode

If your app supports dark mode, your HUD should look good in both light and dark appearances. The simplest way is to use dynamic colors that change with the system appearance. Instead of setting a fixed black or white color, use a color that adapts, such as the system background color or a color from your asset catalog that has light and dark variants. The HUD will then match the rest of your interface in both modes without extra code.

Test the HUD in both appearances before you ship. Run the app, switch the system to dark mode, and show the HUD. Check that the label is readable, the spinner is visible, and the bezel does not blend into the background. A white bezel on a white screen is hard to see, and a black bezel on a black screen has the same problem. A small amount of contrast makes the HUD readable in every appearance.

Here is a short checklist for a clean customization:

Confirm you set the label and details label text before you show the HUD
Confirm you picked fonts and colors that match the rest of your app
Confirm you set the bezel and background colors for the look you want
Confirm you picked a fade or zoom animation that fits your app’s tone
Confirm you set a grace time and a minimum show time for smooth timing
Confirm you leave removeFromSuperViewOnHide at its default unless you have a reason to change it

Conclusion

Customizing MBProgressHUD is a set of small changes that add up to a big difference. You can change the label and details label text and fonts, the content color, the bezel color, the background dimming, the animation type, the margin, and the timing. A grace time and a minimum show time keep the HUD smooth for fast and slow tasks alike. The default look is already clean, so you do not need to change everything. Pick the two or three options that matter for your app, match them to your design, and leave the rest alone. A HUD that looks like part of your app feels more polished than a HUD that looks like an add-on.