Available from v8.0.0
BB.ProgressIndicator
A SwiftUI horizontal progress bar that visualizes determinate progress from 0 to 1, with design-system-driven coloring and appearance presets. The component maps to UIKit's intent while using SwiftUI rendering, and clamps progress values safely to the 0...1 range.
Platform availability: iOS 17.0+
When to use:
- Use BB.ProgressIndicator when you can measure and display actual progress as a percentage.
- Consider BB.LoadingIndicator when the operation duration is unknown or indeterminate.
Import
import SwiftUI
import BackbaseDesignSystem
Visual reference
|
|
|
|
API reference
BB.ProgressIndicator
Enumerations
Appearance
The Appearance enumeration defines the visual style for the progress indicator.
|
Value |
Description |
|---|---|
|
.default |
Brand progress color on subtle brand track |
|
.inverted |
Subtle brand progress color on an on-background track (for dark surfaces) |
|
.success |
Success color fill on a transparent track |
Initializers
init(appearance:progress:)
Creates a new progress indicator with the specified appearance and a binding to progress.
|
Parameter |
Type |
Description |
|---|---|---|
|
appearance |
Appearance |
The visual style for the surface (defaults to .default) |
|
progress |
Binding<Double> |
A binding to a normalized value in the range 0...1 |
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
appearance |
Appearance |
.default |
|
progress |
Binding<Double> |
Required |
appearance
The appearance property determines the color scheme of the progress bar based on the surface it appears on.
BB.ProgressIndicator(appearance: .inverted, progress: $progress)
progress
The progress property is a binding to the current progress value. Values should be normalized to the range 0...1. Out-of-range values are clamped automatically.
@State private var progress: Double = 0.5
BB.ProgressIndicator(progress: $progress)
Usage
Basic usage
Display a progress indicator with a binding to the current progress value.
import SwiftUI
import BackbaseDesignSystem
struct ExampleView: View {
@State private var progress: Double = 0.35
var body: some View {
BB.ProgressIndicator(progress: $progress)
}
}
Inverted style on dark surface
Use the inverted appearance when displaying on dark surfaces.
import SwiftUI
import BackbaseDesignSystem
struct ExampleView: View {
@State private var progress: Double = 0.35
var body: some View {
BB.ProgressIndicator(progress: $progress)
}
}
Success style
Use the success appearance to indicate completed or successful progress.
import SwiftUI
import BackbaseDesignSystem
struct ExampleView: View {
var body: some View {
BB.ProgressIndicator(appearance: .success, progress: .constant(1.0))
}
}
Animated progress
Animate progress changes smoothly.
import SwiftUI
import BackbaseDesignSystem
struct ExampleView: View {
@State private var progress: Double = 0.0
var body: some View {
VStack {
BB.ProgressIndicator(progress: $progress)
Button("Start") {
withAnimation(.linear(duration: 2.0)) {
progress = 1.0
}
}
}
}
}
Download progress example
Display progress for a download operation.
import SwiftUI
import BackbaseDesignSystem
struct DownloadView: View {
@State private var downloadProgress: Double = 0.0
@State private var isDownloading = false
var body: some View {
VStack(spacing: 16) {
BB.ProgressIndicator(progress: $downloadProgress)
Text("\(Int(downloadProgress * 100))%")
Button(isDownloading ? "Downloading..." : "Download") {
startDownload()
}
.disabled(isDownloading)
}
}
private func startDownload() {
isDownloading = true
downloadProgress = 0.0
Timer.scheduledTimer(withTimeInterval: 0.1, repeats: true) { timer in
downloadProgress += 0.05
if downloadProgress >= 1.0 {
timer.invalidate()
isDownloading = false
}
}
}
}
States and variants
Default appearance
The standard appearance for light or neutral backgrounds.
Visual characteristics:
- Brand color for the progress fill
- Subtle brand color for the track background
BB.ProgressIndicator(progress: $progress)
Inverted appearance
The appearance for dark surfaces.
Visual characteristics:
- Subtle brand color for the progress fill
- On-background subtle brand color for the track
- High contrast on dark surfaces
ZStack {
Color.black
BB.ProgressIndicator(appearance: .inverted, progress: $progress)
}
Success appearance
The appearance for indicating successful completion.
Visual characteristics:
- Success color for the progress fill
- Transparent track background
- Suitable for completed states
BB.ProgressIndicator(appearance: .success, progress: .constant(1.0))
Customization
Appearance selection
Choose the appropriate appearance based on your surface and context.
// For light backgrounds
BB.ProgressIndicator(appearance: .default, progress: $progress)
// For dark backgrounds
BB.ProgressIndicator(appearance: .inverted, progress: $progress)
// For success states
BB.ProgressIndicator(appearance: .success, progress: $progress)
Best practices
- Normalize progress values to the 0...1 range. The component clamps out-of-range values but it is better to normalize at source.
- Use .inverted when placed on dark/on-color surfaces for proper contrast.
- Use this component only when you know the progress. For unknown durations, use BB.LoadingIndicator.
Accessibility
This component can be configured with accessibility features at the integration level. Use the standard SwiftUI accessibility modifiers to ensure a fully accessible experience for all users.
Accessibility configuration
|
Modifier |
Description |
|---|---|
|
.accessibilityLabel(_:) |
Sets the accessibility label for screen readers |
|
.accessibilityHint(_:) |
Provides additional context for the action |
|
.accessibilityValue(_:) |
Sets the current value for the element |
Best practices
- Provide meaningful accessibility labels that describe the element's purpose.
- Use accessibility hints to provide additional context when needed.
- Ensure all interactive elements are accessible.
BB.ProgressIndicator(progress: $progress)
.accessibilityLabel("Descriptive label")
.accessibilityHint("Additional context")
Dependencies
- External dependencies: None
- Internal dependencies: BackbaseDesignSystem
Design tokens
Component styling is applied automatically through the design system's theming infrastructure.
JSON tokens
This component uses semantic tokens only. See Semantic tokens below.
Semantic tokens
Default appearance tokens:
|
Token |
API Reference |
Description |
|---|---|---|
|
Progress color |
Theme.colors.background.brand |
Brand color for the progress fill |
|
Track color |
Theme.colors.background.brandSubtle |
Subtle brand color for the track background |
Inverted appearance tokens:
|
Token |
API Reference |
Description |
|---|---|---|
|
Progress color |
Theme.colors.background.brandSubtle |
Subtle brand color for the progress fill |
|
Track color |
Theme.colors.onBackground.brandSubtle |
On-background subtle brand color for the track |
Success appearance tokens:
|
Token |
API Reference |
Description |
|---|---|---|
|
Progress color |
Theme.colors.background.success |
Success color for the progress fill |
|
Track color |
Color.clear |
Clear background for the track |
See also
- BB.LoadingIndicator - For indeterminate loading states
- BB.Shimmer - For skeleton loading states