# ProgressHUD: A SwiftUI HUD for iOS, and What the 15.x Rewrite Means for UIKit Apps

> ProgressHUD is a small MIT-licensed iOS library for showing loading spinners, banners and success or failure states. Version 15.x targets SwiftUI only, while UIKit apps stay on the 14.x line, and that split is the first thing to settle before you add the package.

**relatedcode/ProgressHUD** — ProgressHUD is a lightweight and easy-to-use HUD for iOS. Over 5000+ animations.

- Repository: https://github.com/relatedcode/ProgressHUD
- Website: https://starter.page
- Stars: 2,967 · Forks: 506
- Language: Swift
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/relatedcode-progresshud

## The problem ProgressHUD solves, and who it is actually for

Every iOS app eventually needs to say "something is happening" without taking over the screen. A full-screen modal is too heavy for a two-second network call, and a plain UIActivityIndicatorView gives you no text, no success tick and no banner. ProgressHUD fills that gap with one API surface: a spinner with a label, a progress ring, a transient banner, and short success, failure or item-added states.

The audience is narrow on purpose. The README states the requirements as iOS 17.0+ and Xcode 15.0+, and the note at the top of the README is explicit: "15.x is SwiftUI. For UIKit, use 14.x releases." So this is a library for teams already on a modern SwiftUI deployment target, not for a codebase still supporting iOS 15 or a mixed UIKit stack. If you are maintaining an older app, the repository still carries a Package-UIKit.swift manifest alongside Package-SwiftUI.swift, which tells you both lines are kept in the tree rather than the old one being deleted.

The customization surface is where the library earns its keep. Colors, fonts, media size, margin size, success and error images and the active animation type are all set through static properties such as ProgressHUD.colorHUD and ProgressHUD.animationType, so a design system can be applied once at launch instead of at each call site.

## How the HUD attaches to your view hierarchy in SwiftUI

The mechanism is a view modifier, not a window overlay. The README's SwiftUI setup adds .progressHUD() to the root view inside the WindowGroup, which means the HUD is rendered as part of the SwiftUI tree and inherits that view's lifetime and environment. This is a different design from the older UIKit HUDs, which typically add a subview to the key window and therefore survive navigation changes on their own.

The consequence is worth stating plainly: if the modifier is not on the view that is currently on screen, the calls have nowhere to draw. Putting it on the root view, as the README shows, is the safe placement. The static API is then global in style (ProgressHUD.animate, ProgressHUD.succeed, ProgressHUD.dismiss), which reads well but hides the fact that a view has to be mounted for it to work.

Animation is selected by an enum with 22 cases, listed in full in the README: none, activityIndicator, ballVerticalBounce, barSweepToggle, circleArcDotSpin, circleBarSpinFade, circleDotSpinFade, circlePulseMultiple, circlePulseSingle, circleRippleMultiple, circleRippleSingle, circleRotateChase, circleStrokeSpin, dualDotSidestep, horizontalBarScaling, horizontalDotScaling, pacmanProgress, quintupleDotDance, semiRingRotation, sfSymbolBounce, squareCircuitSnake and triangleDotShift. The default is not stated in the README, so treat selection as something you set explicitly. There is a second enum, LiveIcon, with succeed, failed and added cases, which backs the success, error and added states.

Progress is not observed, it is reported. ProgressHUD.progress(0.15) and ProgressHUD.progress("Loading...", 0.42) take a Double between 0 and 1 that your own code has to compute. There is no URLSession delegate hook or Combine publisher in the documented API, so wiring a download to the ring is your job.

## Installing ProgressHUD as a Swift package and showing a first spinner

The README documents Swift Package Manager first. In Xcode, open File -> Add Package Dependencies..., paste the repository URL into the search bar, choose the version and click Add Package. The URL is the one the README gives:

```bash
https://github.com/relatedcode/ProgressHUD.git
```

If you would rather not use a dependency manager, the README's manual path is to copy all the *.swift files from the SwiftUI/Sources folder into your Xcode project. That folder name matches the SwiftUI directory in the repository root, so the manual route is tied to the 15.x line.

Once the package is added, attach the modifier to your root view. This is the exact structure from the README's quick start:

```swift
import SwiftUI

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .progressHUD()
        }
    }
}
```

With that in place, a loading state is one line. The README's example shows a label and, optionally, a specific animation:

```swift
ProgressHUD.animate("Please wait...", .ballVerticalBounce)
```

What you should see is a HUD over the content view with the text "Please wait..." and the ballVerticalBounce animation. To end it, call ProgressHUD.dismiss() or ProgressHUD.remove(); the README lists both without explaining the difference between them, which is a gap worth checking in the source before you standardize on one. A success state is equally short:

```swift
ProgressHUD.succeed("Some text...", delay: 1.5)
```

The delay parameter appears on both the banner and succeed calls, so the HUD dismisses itself after that many seconds without a second call.

## Where ProgressHUD is the wrong tool

The iOS 17.0 floor is the hardest constraint. Any app that still supports iOS 16 or earlier cannot use 15.x at all, and the README does not describe a back-deployment shim. Since 15.x is SwiftUI, a UIKit view controller has no documented way to call into it either; the README's answer is to use the 14.x releases, which means an app with both SwiftUI and UIKit screens either pins two versions across two targets or stays on 14.x everywhere.

The second limitation is scope. ProgressHUD draws states; it does not manage them. There is no queue, no reference counting and no automatic dismissal when a task finishes. If two asynchronous operations both call ProgressHUD.animate and one finishes first, the documented API gives you no way to know whether the remaining call still owns the HUD. Long-lived apps that fire overlapping requests will need their own coordination layer around the static calls.

The third is interaction. ProgressHUD.animate("Some text...", interaction: false) exists, which implies the default blocks user interaction, but the README does not spell out what the flag does in each state. If your design requires a non-blocking spinner over a still-tappable list, verify the behaviour rather than assuming it.

Finally, the README does not document rollback or version pinning strategy beyond "choose the version you want to use" in the Xcode flow. Given that 14.1.5 and 15.0.x were both released in the same period, pinning an exact version in your package manifest is the only way to avoid a silent major-line switch.

## ProgressHUD against MBProgressHUD and SVProgressHUD

The related searches around this project are dominated by the older UIKit HUDs, which is a fair comparison because the difference is architectural rather than cosmetic. MBProgressHUD and SVProgressHUD are UIKit libraries that attach to a window or a view and are driven from view controllers. ProgressHUD 15.x is a SwiftUI modifier driven by static calls. If your app is SwiftUI-first, the older libraries require bridging through UIViewRepresentable or a window lookup, which is the friction ProgressHUD removes.

JGProgressHUD sits in the same UIKit camp, and the search data shows people asking about it in a SwiftUI context, which is exactly the mismatch ProgressHUD is positioned against. The trade is that the UIKit libraries have a longer track record and, in many codebases, an existing wrapper you would have to rewrite.

The animation count is where ProgressHUD differentiates itself: 22 named cases in the AnimationType enum, from activityIndicator through pacmanProgress to triangleDotShift. The older HUDs offer a smaller set and expect you to supply custom views for anything unusual. That is a real advantage if you want a distinctive loading state without writing Core Animation code, and a non-issue if you only ever show the system spinner.

## Maintenance, versioning and the MIT licence

The repository is not archived, and the last push was on 2026-09-13, the same day as the 15.0.3 release. The release history shows 14.1.5 and 15.0.2 both published on 2026-08-02, and 15.0.3 on 2026-09-13. That pattern says the 14.x line is still receiving releases alongside 15.x, so a UIKit app is not stranded, but the README's own note still points UIKit users at 14.x rather than promising parity.

Upgrade cost is concentrated in the 14 to 15 jump. Moving from 14.x to 15.x is a major-version change that also moves you from UIKit to SwiftUI, so it is not a version bump you take casually. Within 15.x, the patch releases (15.0.2, 15.0.3) suggest incremental fixes, and the README defers detail to CHANGELOG.md, which is present in the repository root. Read that file before upgrading rather than the README, which only links to it.

The licence is MIT, Copyright (c) 2026 Related Code. The grant permits use, copy, modification, merge, publication, distribution, sublicensing and sale, with the condition that the copyright notice and permission notice are included in all copies or substantial portions. The software is provided "AS IS", without warranty of any kind, and the authors are not liable for claims or damages. For a closed-source app the practical requirement is keeping the notice in your acknowledgements; this is a description of the licence text, not legal advice.

## Conclusion

Adopt ProgressHUD if your app is SwiftUI on iOS 17 or later and you want a single modifier plus static calls for spinners, banners and progress. Do not adopt it if you still ship UIKit screens, because 15.x is SwiftUI and the README points UIKit users at 14.x; do not expect a progress bar driven by a network delegate, since the API takes a Double you supply. Before wiring it in, verify that your deployment target is iOS 17.0 and your Xcode is 15.0 or newer, and confirm which of the two package manifests (Package-SwiftUI.swift or Package-UIKit.swift) matches the line you picked.

## FAQ

### What is a HUD in programming?

A HUD is a heads-up display: a small overlay drawn on top of the app's content to show a status such as loading, success or failure. In ProgressHUD it is the layer that shows a spinner with a label, a progress ring or a transient banner.

### Does ProgressHUD work with UIKit, or only SwiftUI?

The README states that 15.x is SwiftUI and that UIKit users should use the 14.x releases. The repository carries both Package-SwiftUI.swift and Package-UIKit.swift, so both lines exist in the tree.

### What are the minimum requirements for ProgressHUD 15.x?

The README lists iOS 17.0+ and Xcode 15.0+ under Requirements. Anything below that cannot use the 15.x line.

### How do I install ProgressHUD with Swift Package Manager?

In Xcode, use File -> Add Package Dependencies..., paste https://github.com/relatedcode/ProgressHUD.git into the search bar, pick a version and click Add Package. The README also offers a manual route: copy the *.swift files from SwiftUI/Sources into your project.

### How do I show a loading spinner with ProgressHUD?

Add the .progressHUD() modifier to your root view, then call ProgressHUD.animate with a message, optionally followed by an animation type such as .ballVerticalBounce. ProgressHUD.dismiss() or ProgressHUD.remove() ends it.

## Sources

- [License: MIT](https://github.com/relatedcode/ProgressHUD/blob/master/LICENSE)
- [Project website](https://starter.page)
- [README](https://github.com/relatedcode/ProgressHUD/blob/master/README.md)
- [relatedcode/ProgressHUD on GitHub](https://github.com/relatedcode/ProgressHUD)
- [Releases](https://github.com/relatedcode/ProgressHUD/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/relatedcode-progresshud