Available from v8.0.0
BB.StateView
BB.StateView is a customizable state view component for displaying various states such as no results, no connection, and loading failures.
Platform availability: iOS 17.0+
When to use:
- Use BB.StateView when content cannot be displayed due to empty results, connectivity issues, or loading failures that require user action.
- Consider BB.Shimmer for loading placeholders or BB.LoadingIndicator for in-progress states without error conditions.
Import
import SwiftUI
import BackbaseDesignSystem
Visual reference
|
|
|
|
API reference
BB.StateView
A view that displays various states with flexible content arrangement including a graphic, primary and secondary text, and up to three action buttons.
Initializers
- init(graphic:labelPrimaryText:labelSecondaryText:primaryButton:secondaryButton:tertiaryButton:)
- Initializes a new state view instance with customizable content and actions.
|
Parameter |
Type |
Description |
|---|---|---|
|
graphic |
Graphic |
The main visual element displayed in the state view |
|
labelPrimaryText |
String |
The primary text message displayed in the state view |
|
labelSecondaryText |
String? |
Optional secondary text message displayed below the primary text |
|
primaryButton |
BB.Button? |
Optional primary action button |
|
secondaryButton |
BB.Button? |
Optional secondary action button |
|
tertiaryButton |
BB.Button? |
Optional tertiary action button |
Factory methods
- noResults(labelPrimaryText:labelSecondaryText:)
- Creates a state view for displaying a "no results" state.
|
Parameter |
Type |
Description |
|---|---|---|
|
labelPrimaryText |
String |
Custom primary text. Uses the default "No Results" title if not specified |
|
labelSecondaryText |
String |
Custom secondary text. Uses the default "No Results" subtitle if not specified |
Returns: BB.StateView - A configured state view for empty results
- noConnection(labelPrimaryText:labelSecondaryText:primaryButtonText:primaryButtonAction:)
- Creates a state view for displaying a "no connection" state.
|
Parameter |
Type |
Description |
|---|---|---|
|
labelPrimaryText |
String |
Custom primary text. Uses the default "No Connection" title if not specified |
|
labelSecondaryText |
String |
Custom secondary text. Uses the default "No Connection" subtitle if not specified |
|
primaryButtonText |
String |
Custom text for the primary button. Uses the default button text if not specified |
|
primaryButtonAction |
() -> Void |
The action to perform when the primary button is tapped |
Returns: BB.StateView - A configured state view for connectivity issues
- loadingFailure(labelPrimaryText:labelSecondaryText:primaryButtonText:primaryButtonAction:)
- Creates a state view for displaying a "loading failure" state.
|
Parameter |
Type |
Description |
|---|---|---|
|
labelPrimaryText |
String |
Custom primary text. Uses the default "Loading Failure" title if not specified |
|
labelSecondaryText |
String |
Custom secondary text. Uses the default "Loading Failure" subtitle if not specified |
|
primaryButtonText |
String |
Custom text for the primary button. Uses the default button text if not specified |
|
primaryButtonAction |
() -> Void |
The action to perform when the primary button is tapped |
Returns: BB.StateView - A configured state view for loading errors
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
graphic |
Graphic |
— |
|
labelPrimaryText |
String |
— |
|
labelSecondaryText |
String? |
nil |
|
primaryButton |
BB.Button? |
nil |
|
secondaryButton |
BB.Button? |
nil |
|
tertiaryButton |
BB.Button? |
nil |
graphic
The graphic property defines the main visual element displayed at the top of the state view. This can be an image, icon, or Lottie animation.
BB.StateView(
graphic: DesignSystem.Images.icStateViewNoWifi(),
labelPrimaryText: "No Connection"
)
labelPrimaryText
The labelPrimaryText property sets the primary text message displayed in the state view. This should clearly communicate the current state.
BB.StateView(
graphic: DesignSystem.Images.icStateViewNoResults(),
labelPrimaryText: "No results found"
)
labelSecondaryText
The labelSecondaryText property sets optional secondary text displayed below the primary text for additional context or guidance.
BB.StateView(
graphic: DesignSystem.Images.icStateViewNoResults(),
labelPrimaryText: "No results found",
labelSecondaryText: "Try adjusting your search criteria"
)
primaryButton, secondaryButton, tertiaryButton
The button properties add action buttons to the state view. Use buttons when there are meaningful actions users can take.
BB.StateView(
graphic: DesignSystem.Images.icStateViewNoWifi(),
labelPrimaryText: "No Connection",
primaryButton: BB.Button(text: "Try Again") { },
secondaryButton: BB.Button(text: "Settings", appearance: .secondary) { }
)
Usage
Basic usage
Use the factory methods for common state views.
BB.StateView.noResults()
BB.StateView.noConnection { print("Retry tapped") }
BB.StateView.loadingFailure { print("Retry tapped") }
Custom state view
Create a custom state view with your own graphic and text.
BB.StateView(
graphic: DesignSystem.Images.icStateViewNoWifi(),
labelPrimaryText: "Custom State",
labelSecondaryText: "This is a custom state view"
)
State view with Lottie animation
Use animated graphics with the state view.
BB.StateView(
graphic: LottieView(animation: .named("success-animation"))
.playbackMode(.playing(.toProgress(1, loopMode: .loop))),
labelPrimaryText: "Animated",
labelSecondaryText: "Using a lottie animation",
primaryButton: BB.Button(text: "Primary Action") { print("Primary pressed!") },
secondaryButton: BB.Button(text: "Secondary Action", appearance: .secondary) { print("Secondary pressed!") },
tertiaryButton: BB.Button(text: "Tertiary Action", appearance: .tertiary) { print("Tertiary pressed!") }
)
States and variants
No results
The noResults state is used when a search or query returns no matching items.
Visual characteristics:
- Empty state graphic
- Default "No results to show" message
- No action button by default
BB.StateView.noResults()
// With custom text
BB.StateView.noResults(
labelPrimaryText: "No transactions found",
labelSecondaryText: "Try changing your filter criteria"
)
No connection
The noConnection state is used when network connectivity is unavailable.
Visual characteristics:
- No WiFi graphic
- Default "No internet connection" message
- "Try again" button for retry action
BB.StateView.noConnection {
// Retry connection
}
// With custom text
BB.StateView.noConnection(
labelPrimaryText: "You're offline",
labelSecondaryText: "Check your connection and try again",
primaryButtonText: "Retry"
) {
// Retry action
}
Loading failure
The loadingFailure state is used when content fails to load due to an error.
Visual characteristics:
- Error graphic
- Default "Couldn't load page" message
- "Try again" button for retry action
BB.StateView.loadingFailure {
// Reload content
}
// With custom text
BB.StateView.loadingFailure(
labelPrimaryText: "Something went wrong",
labelSecondaryText: "We couldn't load your data",
primaryButtonText: "Reload"
) {
// Reload action
}
Customization
Custom graphics
Use custom images or Lottie animations as the graphic element.
// Using a custom image
BB.StateView(
graphic: Image("custom-empty-state"),
labelPrimaryText: "Custom State"
)
// Using a Lottie animation
BB.StateView(
graphic: LottieView(animation: .named("loading-animation"))
.playbackMode(.playing(.toProgress(1, loopMode: .loop))),
labelPrimaryText: "Loading..."
)
Button configuration
Configure multiple action buttons with different appearances.
BB.StateView(
graphic: DesignSystem.Images.icStateViewError(),
labelPrimaryText: "Error Occurred",
labelSecondaryText: "Would you like to retry?",
primaryButton: BB.Button(text: "Retry") { },
secondaryButton: BB.Button(text: "Cancel", appearance: .secondary) { },
tertiaryButton: BB.Button(text: "Help", appearance: .tertiary) { }
)
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.StateView()
.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
|
Token |
API Reference |
Description |
|---|---|---|
|
Primary text color |
Theme.colors.foreground.default |
Color for the primary label text |
|
Secondary text color |
Theme.colors.foreground.subtle |
Color for the secondary label text |
|
Primary typography |
DesignSystem.shared.typography.headline |
Typography style for the primary text |
|
Secondary typography |
DesignSystem.shared.typography.body |
Typography style for the secondary text |
|
Spacing |
DesignSystem.shared.spacer |
Spacing between graphic, text, and buttons |
|
Graphic tint |
Theme.colors.foreground.subtle |
Tint color for default state view graphics |
Localization
The following strings are available for localization:
|
Key |
Default Value |
Description |
|---|---|---|
|
DesignSystem.stateView.noConnectionTitle |
"No internet connection" |
No connection state title |
|
DesignSystem.stateView.noConnectionSubtitle |
"It seems that you're not online" |
No connection state subtitle |
|
DesignSystem.stateView.noConnectionButton |
"Try again" |
No connection retry button |
|
DesignSystem.stateView.noResultsTitle |
"No results to show" |
No results state title |
|
DesignSystem.stateView.noResultsSubtitle |
"We couldn't find anything to show here" |
No results state subtitle |
|
DesignSystem.stateView.loadingFailureTitle |
"Couldn't load page" |
Loading failure state title |
|
DesignSystem.stateView.loadingFailureSubtitle |
"Something went wrong" |
Loading failure state subtitle |
|
DesignSystem.stateView.loadingFailureButton |
"Try again" |
Loading failure retry button |
To customize these strings, add the keys to your app's Localizable.strings file.
See also
- BB.LoadingIndicator - For loading states
- BB.Shimmer - For skeleton loading states
- BB.Button - For action buttons