Guide · Open source
How to use SVProgressHUD: install, show and dismiss a HUD in iOS
Updated · written with AI from the project's own documentation and checked against our catalogue data
SVProgressHUD is an open-source library that shows a small on-screen overlay in an iOS or tvOS app while a task runs, reports progress, or confirms success or failure. This guide is for iOS developers who need a simple loading indicator for a short, blocking task. By the end you will know how to install it, show and dismiss the HUD from Objective-C or Swift, and adjust its appearance.
SVProgressHUDSVProgressHUD/SVProgressHUD · ★ 12.4k · MIT Install options & downloads Quick start
- 1Add the library. Add SVProgressHUD to your project with Swift Package Manager or CocoaPods. For SwiftPM, use File > Add Package Dependency in Xcode.
- 2Show the HUD. Call SVProgressHUD.show() or showWithStatus: before the work that the user must wait for.
- 3Run the task off the main thread. Perform the slow work on a background queue, as shown in the README examples.
- 4Dismiss on the main thread. Call SVProgressHUD.dismiss() on the main queue when the work completes.
- 5Show a result. Use showSuccessWithStatus: or showErrorWithStatus: to confirm the outcome briefly.
- 6Customize the look. Set a style or custom colors, and adjust timing through the appearance and behavior options.
What SVProgressHUD is for and when to avoid it
SVProgressHUD displays the progress of an ongoing task on iOS and tvOS. It is meant for cases where the user has to wait before moving on to the next step.
The README is explicit about misuse. Only use it if you absolutely need to perform a task before taking the user forward. Pull to refresh, infinite scrolling and sending a message are listed as bad use cases.
Install SVProgressHUD with CocoaPods, Swift Package Manager or manually
The README lists several install methods. For Swift Package Manager, use Xcode's File > Add Package Dependency, enter the repository URL, choose a version, and add SVProgressHUD to your target dependencies. The README says it requires at least Swift tools version 5.3.
For CocoaPods, add the pod line to your Podfile and then run pod install. The README also describes Carthage and a manual drag-in method, which requires adding the QuartzCore framework.
- Swift Package Manager: File > Add Package Dependency in Xcode
- CocoaPods: add the pod line to your Podfile, then install
- Manual: drag the SVProgressHUD/SVProgressHUD folder into your project and make sure SVProgressHUD.bundle is in Copy Bundle Resources
pod 'SVProgressHUD'
pod installUse SVProgressHUD from Swift or Objective-C
SVProgressHUD is a singleton, so you do not allocate it. You call its class methods directly. The README shows the usual pattern: show the HUD, run the slow work on a background queue, then dismiss the HUD on the main queue.
Although the library is written in Objective-C, the README says it works in Swift without extra effort. With CocoaPods, add use_frameworks! to your Podfile. If you added the library manually, add a bridging header that includes the SVProgressHUD header.
SVProgressHUD.show()
DispatchQueue.global(qos: .default).async {
// time-consuming task
DispatchQueue.main.async {
SVProgressHUD.dismiss()
}
}Show, update and dismiss the HUD
Use show or showWithStatus: for tasks with no measurable progress. Use showProgress: or showProgress:status: when you can report a value for the progress.
To close the HUD, call dismiss, or dismissWithDelay: to close it after a set time. If you have nested show calls, popActivity balances each show call, and the HUD is dismissed once the number of popActivity calls matches the number of show calls.
To finish with a message, use showInfoWithStatus:, showSuccessWithStatus:, showErrorWithStatus: or showImage:status:. The README says the display time depends on minimumDismissTimeInterval and the length of the string.
- show / showWithStatus: for indeterminate tasks
- showProgress: / showProgress:status: for known progress
- dismiss / dismissWithDelay: to close
- popActivity to balance nested show calls
- showSuccessWithStatus:, showErrorWithStatus:, showInfoWithStatus:, showImage:status: for a brief result
+ (void)showWithStatus:(NSString*)string;
+ (void)showProgress:(CGFloat)progress status:(NSString*)status;
+ (void)dismissWithDelay:(NSTimeInterval)delay;
+ (void)showSuccessWithStatus:(NSString*)string;Customize colors, fonts and timing
The README says SVProgressHUD supports UI_APPEARANCE_SELECTOR, so you can adjust styles, colors, fonts, size and images across your app. You can also control visibility durations, display delays and animation speeds.
There are three preconfigured styles: Automatic, Light and Dark. Calling setForegroundColor: or setBackgroundColor: switches the HUD to the Custom style. The README also describes optional haptic feedback, available on iPhone 7 and newer, which you turn on with setHapticsEnabled:.
- SVProgressHUDStyleAutomatic: switches between light and dark
- SVProgressHUDStyleLight: white background, black spinner and text
- SVProgressHUDStyleDark: black background, white spinner and text
- SVProgressHUDStyleCustom is set implicitly by setForegroundColor: or setBackgroundColor:
Listen for HUD events with notifications
SVProgressHUD posts four notifications through NSNotificationCenter: WillAppear and DidAppear when the show animation starts and completes, and WillDisappear and DidDisappear for the dismiss animation. Each carries the status string in userInfo under SVProgressHUDStatusUserInfoKey.
Touch notifications are also available. SVProgressHUDDidReceiveTouchEventNotification fires on touches anywhere on the screen, and SVProgressHUDDidTouchDownInsideNotification fires when the user touches the HUD itself.
Use SVProgressHUD in an App Extension
For App Extensions, the README says to define SV_APP_EXTENSIONS to avoid unavailable APIs. This is done automatically when you use the AppExtension CocoaPods subspec. You also call setViewForExtension: from your extension's view controller, passing self.view.
#define SV_APP_EXTENSIONSWhat people use it for
- Show a loading indicator while an app saves or uploads data the user must wait for
- Display a brief success message after a user completes an action
- Show an error status when a blocking request fails
- Report progress of a task with showProgress:status:
- Apply one consistent HUD style across an iOS or tvOS app
Frequently asked questions
Is SVProgressHUD free to use?
The README says SVProgressHUD is distributed under the MIT license, as listed on the repository. The license text is in the project, so check it there before shipping.
What do I need to install SVProgressHUD?
You need Xcode. For Swift Package Manager, the README says you need at least Swift tools version 5.3. The library supports iOS and tvOS.
How do I install SVProgressHUD with CocoaPods?
Add pod 'SVProgressHUD' to your Podfile and run pod install. The README also shows an option to pull from the master branch with an external git source.
Can I use SVProgressHUD in Swift?
Yes. The README says it is written in Objective-C but works in Swift with no hassle. Use use_frameworks! with CocoaPods, or a bridging header for a manual install.
Can I use SVProgressHUD for pull to refresh?
No. The README specifically says not to use it for pull to refresh, infinite scrolling or sending a message. It is for short waits where the user must wait before moving on.
How does SVProgressHUD compare to MBProgressHUD or JGProgressHUD?
The README does not compare it to other libraries, so this guide cannot make a claim. Comparable projects include MBProgressHUD, JGProgressHUD and PKHUD. Compare their APIs and styling options against your needs.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
SVProgressHUD suits iOS and tvOS developers, especially in Objective-C codebases, who need a drop-in HUD for short blocking tasks and brief success or error messages. Skip it for background refreshes, non-Apple platforms, or projects that want a fully SwiftUI-native indicator, since the README does not cover those cases.
Install options & downloads