MBProgressHUD in Swift: Bridging Header Guide

MBProgressHUD is written in Objective-C, but most new iOS apps are written in Swift. That combination works fine, but you need to connect the two languages first. The connection is called a bridging header, and it is a small file that tells Swift how to see your Objective-C code. This guide explains how to set up a bridging header for MBProgressHUD, how to import the library in Swift, and how to fix the common errors that show up along the way.

Before you start, make sure MBProgressHUD is installed in your project. If you installed it with Swift Package Manager, you do not need a bridging header at all, because the package exposes MBProgressHUD as a module and you can import it directly with import MBProgressHUD. A bridging header is needed when you install MBProgressHUD with CocoaPods without frameworks, with Carthage, or by adding the source files directly to your project. The install guides in this series cover each method.

What a Bridging Header Does

A bridging header is a header file that lists the Objective-C headers your Swift code needs to see. When Xcode builds your project, it reads the bridging header and makes those Objective-C classes available in Swift. Without it, Swift cannot see MBProgressHUD at all, and your code will fail to compile with a “cannot find type” error.

The bridging header is a normal .h file, and it usually has a name like YourProjectName-Bridging-Header.h. It sits in your project folder, and Xcode knows about it through a build setting called Objective-C Bridging Header. Once that setting points to your file, any Objective-C header you list in the file becomes visible to every Swift file in your project.

Create the Bridging Header

The easiest way to create a bridging header is to let Xcode do it for you. Add a new Objective-C file to your Swift project, such as an empty .m file. Xcode will notice that your project has no bridging header yet, and it will ask if you want to create one. Click yes, and Xcode will create the header file and set the build setting for you. You can then delete the empty Objective-C file you just added, because you only needed it to trigger the prompt.

If Xcode does not ask, you can create the header by hand. Add a new header file to your project and name it YourProjectName-Bridging-Header.h. Then open your project settings, select your app target, go to Build Settings, and search for “Objective-C Bridging Header”. Set the value to the path of your new file, such as YourProjectName/YourProjectName-Bridging-Header.h. The path is relative to your project folder.

Add the MBProgressHUD Import

Open the bridging header file and add one line: #import “MBProgressHUD.h” if you added the source files directly to your project, or #import <MBProgressHUD/MBProgressHUD.h> if you installed it as a framework through CocoaPods or Carthage. The difference matters. Quotes mean the header is a file in your project. Angle brackets mean the header comes from a framework. If you use the wrong one, the build will fail with a “file not found” error.

Once the import is in place, you can use MBProgressHUD in any Swift file without importing it again. The bridging header makes it visible everywhere. You can write MBProgressHUD.showAdded(to: self.view, animated: true) in a view controller, and it will compile. You do not need an import MBProgressHUD line in your Swift files when you use a bridging header.

Use the Swift API

The Swift API for MBProgressHUD is a direct translation of the Objective-C API, and it feels natural in Swift. To show the HUD, write let hud = MBProgressHUD.showAdded(to: self.view, animated: true). To hide it, write hud.hide(animated: true). To show it for a specific view and hide it later, write MBProgressHUD.hide(for: self.view, animated: true). The method names are the same as in Objective-C, but the syntax follows Swift rules.

One detail to watch is the label. In Swift, you set the label with hud.label.text = “Loading”. In Objective-C, you set it with hud.label.text = @”Loading”. The property names are the same, and only the string syntax changes. The same is true for the details label, the mode, the progress value, and every other setting.

Fix the Common Import Errors

The most common error is “no such module” when you write import MBProgressHUD in Swift. That error means you are mixing two approaches. If you use a bridging header, do not write import MBProgressHUD in your Swift files, because the bridging header already exposes the class. If you want to use import MBProgressHUD, install the library as a module through Swift Package Manager or CocoaPods with use_frameworks!, and do not use a bridging header at all.

Another common error is “file not found” for the header itself. That usually means you used quotes when you should have used angle brackets, or the other way around. Check how you installed the library, then match the import style to it. A third common error is a deployment target mismatch. If your project targets an iOS version older than 9.0, the library will not build. Raise the deployment target in your project settings to 9.0 or higher.

Call Objective-C Methods from Swift

Once the bridging header is set up, you can call any MBProgressHUD method from Swift, and the method names translate in a predictable way. Objective-C methods with colons become Swift methods with labels. For example, the Objective-C call [MBProgressHUD showHUDAddedTo:self.view animated:YES] becomes MBProgressHUD.showAdded(to: self.view, animated: true) in Swift. The meaning is the same, and only the syntax changes.

Properties work the same way. In Objective-C, you write hud.label.text = @”Loading”. In Swift, you write hud.label.text = “Loading”. The property names are identical, and only the string literal changes, because Swift strings do not need the @ sign. The same is true for numbers, booleans, and every other value. If you know the Objective-C API, you already know the Swift API, because the names carry over directly.

One detail to watch is optionals. Some Objective-C properties can be nil, and Swift treats those as optionals. The label property, for example, is always present on a HUD, so you can use it directly. If Xcode warns you about an optional, unwrap it safely with optional binding or optional chaining, and the warning will go away.

Here is a short checklist for a clean Swift setup:

Confirm you know whether you need a bridging header or a module import for your install method
Confirm the bridging header file exists and the build setting points to it
Confirm you used quotes for source files and angle brackets for a framework
Confirm you do not mix a bridging header import with a module import in Swift
Confirm your project targets iOS 9.0 or later with ARC enabled
Confirm the project builds and the HUD appears when you run the app

Conclusion

Using MBProgressHUD in Swift is simple once you pick one approach and stick to it. If you install it with Swift Package Manager, import it as a module with import MBProgressHUD and skip the bridging header. If you install it with CocoaPods without frameworks, with Carthage, or by adding the source files, create a bridging header, add the right import line, and use the class directly in Swift. Quotes are for source files in your project, and angle brackets are for frameworks. If the build fails, check the import style, check that you are not mixing both approaches, and check your deployment target. With the setup done, you can use the full MBProgressHUD API in Swift, and the next guides in this series show you exactly how.