Skip to content

Commit d2620c8

Browse files
fxm90fxm90
committed
📝 :: Update documentation
1 parent 132755a commit d2620c8

File tree

2 files changed

+346
-254
lines changed

2 files changed

+346
-254
lines changed

‎README.md‎

Lines changed: 346 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,346 @@
1+
# Gradient Loading Bar
2+
3+
![Swift6.2](https://img.shields.io/badge/Swift-6.2-green.svg?style=flat) ![CI Status](https://img.shields.io/github/actions/workflow/status/fxm90/GradientLoadingBar/continuous-integration.yml?branch=feature/version-4) ![Code Coverage](https://img.shields.io/codecov/c/github/fxm90/GradientLoadingBar.svg?style=flat) ![Version](https://img.shields.io/github/v/release/fxm90/GradientLoadingBar) ![License](https://img.shields.io/github/license/fxm90/GradientLoadingBar?color=333333) ![Platform](https://img.shields.io/badge/platform-iOS-8a8a8a)
4+
5+
A customizable animated gradient loading bar, with full support for **SwiftUI** and **UIKit**.\
6+
Inspired by [iOS 7 Progress Bar on CodePen](https://codepen.io/marcobiedermann/pen/LExXWW).
7+
8+
### Screenshot
9+
10+
![Example][example]
11+
12+
To run the example project, clone this repository and open the project file from the **Example** directory.
13+
14+
## Requirements
15+
16+
- Swift **6.2**
17+
- Xcode **26**
18+
- iOS **26.0+**
19+
20+
### Compatibility Notes
21+
22+
- **iOS < 26.0 / CocoaPods / Carthage support**
23+
Use version **`3.x.x`**
24+
- **iOS < 13.0 support**
25+
Use version **`2.x.x`**
26+
27+
## Installation
28+
29+
### Swift Package Manager
30+
31+
**Gradient Loading Bar** is distributed via **Swift Package Manager (SPM)**. Add it to your Xcode project as a package dependency or adapt your `Package.swift` file.
32+
33+
#### Option 1: Xcode
34+
35+
1. Open your project in **Xcode**
36+
2. Go to **File → Add Packages…**
37+
3. Enter the package URL: `https://github.com/fxm90/GradientLoadingBar`
38+
4. Choose the version rule (e.g. _Up to Next Major_ starting at **4.0.0**)
39+
5. Add the package to your target
40+
41+
#### Option 2: `Package.swift`
42+
43+
If you manage dependencies manually, add this repository to the `dependencies` section of your `Package.swift`:
44+
45+
```swift
46+
dependencies: [
47+
.package(
48+
url: "https://github.com/fxm90/GradientLoadingBar",
49+
from: "4.0.0"
50+
)
51+
]
52+
```
53+
54+
Then reference the product in your target configuration:
55+
56+
```swift
57+
.product(
58+
name: "GradientLoadingBar",
59+
package: "GradientLoadingBar"
60+
)
61+
```
62+
63+
Once the package is added, import the framework where needed:
64+
65+
```swift
66+
import GradientLoadingBar
67+
```
68+
69+
## Overview
70+
71+
This framework provides four types:
72+
73+
- **[`GradientLoadingBar`](#gradientloadingbar)**\
74+
A controller class, managing the visibility of the `GradientActivityIndicatorView` attached to the current key window.
75+
76+
- **[`NotchGradientLoadingBar`](#notchgradientloadingbar)**\
77+
A subclass of `GradientLoadingBar`, wrapping the `GradientActivityIndicatorView` around the iPhone notch.
78+
79+
- **[`GradientActivityIndicatorView`](#gradientactivityindicatorview)**\
80+
A `UIView` containing the gradient with the animation.
81+
82+
- **[`GradientLoadingBarView`](#gradientloadingbarview)**\
83+
A SwiftUI `View` containing the gradient with the animation.
84+
85+
## GradientLoadingBar
86+
87+
`GradientLoadingBar` is a controller-style object that manages a gradient loading bar attached to the app’s key window.
88+
89+
### Usage
90+
91+
For most use cases, prefer the shared instance provided by `GradientLoadingBar.shared`.
92+
93+
```swift
94+
final class UserProfileViewController: UIViewController {
95+
96+
override func viewDidLoad() {
97+
super.viewDidLoad()
98+
99+
GradientLoadingBar.shared.fadeIn()
100+
101+
userProfileService.fetchUserProfile { _ in
102+
// ...
103+
// This needs to be called from the main actor!
104+
GradientLoadingBar.shared.fadeOut()
105+
}
106+
}
107+
}
108+
```
109+
110+
This shared instance can be overridden to customize the loading bar globally.
111+
112+
### Configuration
113+
114+
```swift
115+
let gradientLoadingBar = GradientLoadingBar(
116+
height: 5.0,
117+
isRelativeToSafeArea: false,
118+
)
119+
120+
gradientLoadingBar.gradientColors = [.red, .white, .blue]
121+
gradientLoadingBar.progressAnimationDuration = 4.5
122+
```
123+
124+
#### Parameters
125+
126+
- **`height: CGFloat`**\
127+
Sets the bar height (default: `3.0`)
128+
129+
- **`isRelativeToSafeArea: Bool`**\
130+
Determines whether the bar is positioned relative to the safe area (default: `true`)
131+
132+
| Relative To Safe Area | Ignoring Safe Area |
133+
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
134+
| [![Relative to Safe Area][relative-to-safe-area-thumbnail]][relative-to-safe-area] | [![Ignoring Safe Area][ignoring-safe-area-thumbnail]][ignoring-safe-area] |
135+
136+
The gradient animation is easier to see in a video of the example application:
137+
138+
<details>
139+
<summary>🎬 Relative To Safe Area</summary>
140+
141+
https://github.com/user-attachments/assets/c8a3a117-c164-49f5-9511-aa29b92b5344
142+
</details>
143+
144+
<details>
145+
<summary>🎬 Ignoring Safe Area</summary>
146+
147+
https://github.com/user-attachments/assets/4abad13d-e019-43b3-b3b3-c874ac8f9224
148+
</details>
149+
150+
**Note:** For a third option — wrapping around the iPhone notch — see `NotchGradientLoadingBar`.
151+
152+
#### Properties
153+
154+
- **`gradientColors: [UIColor]`**\
155+
Defines the gradient colors.
156+
157+
- **`progressAnimationDuration: TimeInterval`**\
158+
Controls how fast the gradient animates from left to right.
159+
160+
#### Methods
161+
162+
- **`fadeIn(duration: TimeInterval = 0.33, completion: ((Bool) -> Void)? = nil)`**\
163+
Fades the loading bar in.
164+
165+
- **`fadeOut(duration: TimeInterval = 0.66, completion: ((Bool) -> Void)? = nil)`**\
166+
Fades the loading bar out.
167+
168+
## NotchGradientLoadingBar
169+
170+
`NotchGradientLoadingBar` is a subclass of `GradientLoadingBar` that wraps the bar around the iPhone notch.\
171+
On devices without a notch, it behaves identically to `GradientLoadingBar`.
172+
173+
| iPhone 12 Pro | iPhone 13 Pro Max |
174+
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
175+
| [![iPhone 12 Pro][notch-iphone-12-pro-thumbnail]][notch-iphone-12-pro] | [![iPhone 13 Pro Max][notch-iphone-13-pro-max-thumbnail]][notch-iphone-13-pro-max] |
176+
177+
The gradient animation is easier to see in a video of the example application:
178+
179+
<details>
180+
<summary>🎬 iPhone 12 Pro</summary>
181+
182+
https://github.com/user-attachments/assets/998fe36c-40c5-4c70-9ce8-e7a7f3f126d8
183+
</details>
184+
185+
<details>
186+
<summary>🎬 iPhone 13 Pro Max</summary>
187+
188+
https://github.com/user-attachments/assets/2ff6d717-07f1-4d70-887e-2727d55f2515
189+
</details>
190+
191+
## GradientActivityIndicatorView
192+
193+
If you prefer direct view composition, `GradientActivityIndicatorView` is a `UIView` subclass that can be added to other views — such as `UINavigationBar`, `UIButton` or a custom container.
194+
195+
### Usage
196+
197+
Store an instance as a property, set-up constraints and control the visibility using `fadeIn()` and `fadeOut()`.
198+
199+
```swift
200+
final class UserProfileViewController: UIViewController {
201+
202+
private let gradientActivityIndicatorView = GradientActivityIndicatorView()
203+
204+
// ...
205+
206+
override func viewDidLoad() {
207+
super.viewDidLoad()
208+
209+
gradientActivityIndicatorView.translatesAutoresizingMaskIntoConstraints = false
210+
view.addSubview(gradientActivityIndicatorView)
211+
212+
NSLayoutConstraint.activate([
213+
gradientActivityIndicatorView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
214+
gradientActivityIndicatorView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
215+
gradientActivityIndicatorView.topAnchor.constraint(equalTo: view.topAnchor),
216+
gradientActivityIndicatorView.heightAnchor.constraint(equalToConstant: 3),
217+
])
218+
219+
gradientActivityIndicatorView.fadeIn()
220+
221+
userProfileService.fetchUserProfile { [weak self] _ in
222+
// ...
223+
// Be sure to call this on the main actor!
224+
self?.gradientActivityIndicatorView.fadeOut()
225+
}
226+
}
227+
}
228+
```
229+
230+
### Configuration
231+
232+
```swift
233+
let gradientActivityIndicatorView = GradientActivityIndicatorView()
234+
gradientActivityIndicatorView.gradientColors = [.red, .white, .blue]
235+
gradientActivityIndicatorView.progressAnimationDuration = 4.5
236+
```
237+
238+
#### Properties
239+
240+
- **`isHidden: Bool`**\
241+
Toggles the view visibility and starts / stops the progress animation accordingly.
242+
243+
- **`gradientColors: [UIColor]`**\
244+
Defines the gradient colors.
245+
246+
- **`progressAnimationDuration: TimeInterval`**\
247+
Controls how fast the gradient animates from left to right.
248+
249+
#### Methods
250+
251+
- **`fadeIn(duration: TimeInterval = 0.33, completion: ((Bool) -> Void)? = nil)`**\
252+
Fades the view in.
253+
254+
- **`fadeOut(duration: TimeInterval = 0.66, completion: ((Bool) -> Void)? = nil)`**\
255+
Fades the view out.
256+
257+
- **`animate(isHidden: Bool, duration: TimeInterval, completion: ((Bool) -> Void)? = nil)`**\
258+
Fades the view in- or out, based on the provided hidden flag.
259+
260+
## GradientLoadingBarView
261+
262+
`GradientLoadingBarView` is the SwiftUI equivalent of `GradientActivityIndicatorView`.
263+
264+
### Usage
265+
266+
```swift
267+
struct ContentView: some View {
268+
269+
var body: some View {
270+
GradientLoadingBarView()
271+
.frame(maxWidth: .infinity, maxHeight: 3)
272+
.cornerRadius(1.5)
273+
}
274+
}
275+
```
276+
277+
### Configuration
278+
279+
```swift
280+
GradientLoadingBarView(
281+
gradientColors: [.red, .white, .blue],
282+
progressDuration: 4.5,
283+
)
284+
```
285+
286+
#### Parameters
287+
288+
- **`gradientColors: [Color]`**\
289+
Defines the gradient colors.
290+
291+
- **`progressDuration: TimeInterval`**\
292+
Sets the animation speed.
293+
294+
### Visibility & Animation
295+
296+
Control the visibility using standard SwiftUI view modifiers such as:
297+
298+
- [`opacity(_:)`](<https://developer.apple.com/documentation/swiftui/view/opacity(_:)>)
299+
- [`hidden()`](<https://developer.apple.com/documentation/swiftui/view/hidden()>)
300+
301+
Example with fade animation.
302+
303+
```swift
304+
struct ContentView: some View {
305+
306+
@State
307+
private var isVisible = false
308+
309+
var body: some View {
310+
VStack {
311+
GradientLoadingBarView()
312+
.frame(maxWidth: .infinity, maxHeight: 3)
313+
.cornerRadius(1.5)
314+
.opacity(isVisible ? 1 : 0)
315+
.animation(.easeInOut, value: isVisible)
316+
317+
Button("Toggle visibility") {
318+
isVisible.toggle()
319+
}
320+
}
321+
}
322+
}
323+
```
324+
325+
## Author
326+
327+
Felix Mau
328+
me(@)felix.hamburg
329+
330+
## License
331+
332+
Gradient Loading Bar is released under the **MIT License**. See the `LICENSE` file for details.
333+
334+
[example]: Assets/screen.gif
335+
[ignoring-safe-area]: Assets/ignoring-safe-area.png
336+
[ignoring-safe-area-thumbnail]: Assets/ignoring-safe-area-thumbnail.png
337+
[ignoring-safe-area-animation]: Assets/ignoring-safe-area.mov
338+
[relative-to-safe-area]: Assets/relative-to-safe-area.png
339+
[relative-to-safe-area-thumbnail]: Assets/relative-to-safe-area-thumbnail.png
340+
[relative-to-safe-area-animation]: Assets/relative-to-safe-area.mov
341+
[notch-iphone-12-pro]: Assets/notch-iphone-12-pro.png
342+
[notch-iphone-12-pro-thumbnail]: Assets/notch-iphone-12-pro-thumbnail.png
343+
[notch-iphone-12-pro-animation]: Assets/notch-iphone-12-pro.mov
344+
[notch-iphone-13-pro-max]: Assets/notch-iphone-13-pro-max.png
345+
[notch-iphone-13-pro-max-thumbnail]: Assets/notch-iphone-13-pro-max-thumbnail.png
346+
[notch-iphone-13-pro-max-animation]: Assets/notch-iphone-13-pro-max.mov

0 commit comments

Comments
 (0)