Available from v7.0.0
BB.AsyncEmblem
BB.AsyncEmblem is a SwiftUI view that displays an icon fetched asynchronously from a URL with a shimmer effect during loading.
Platform availability: iOS 17.0+
When to use:
- Use BB.AsyncEmblem when displaying icons or images that need to be fetched from a remote URL.
- Consider BB.Emblem when the icon is available locally and does not require network loading.
Import
import BackbaseDesignSystem
import SwiftUI
Visual reference
|
|
|
|
API reference
BB.AsyncEmblem
Initializers
init(url:placeholder:appearance:layout:contentMode:)
Initializes a new async emblem instance with the specified URL and styling options.
|
Parameter |
Type |
Default |
Description |
|---|---|---|---|
|
url |
URL |
— |
The URL from which the image will be fetched |
|
placeholder |
Image |
icAccountBalance |
The image to display if the network image fails to load |
|
appearance |
BB.Emblem.Appearance |
.brand |
The appearance style for the emblem |
|
layout |
BB.Emblem.Layout |
.medium |
The layout size/type of the emblem |
|
contentMode |
ContentMode |
.fit |
Specifies how the image should fit within the view's bounds |
Protocols
BB.AsyncEmblemImageLoader
A protocol for customizing image loading behavior.
public protocol AsyncEmblemImageLoader {
func loadImage(from url: URL) async throws -> Image
}
Assign a custom image loader to DesignSystem.shared.emblemImageLoader to override default loading behavior.
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
url |
URL |
— |
|
placeholder |
Image |
icAccountBalance |
|
appearance |
BB.Emblem.Appearance |
.brand |
|
layout |
BB.Emblem.Layout |
.medium |
|
contentMode |
ContentMode |
.fit |
url
The url property sets the URL from which the image will be fetched asynchronously.
let imageUrl = URL(string: "https://example.com/image.png")!
BB.AsyncEmblem(url: imageUrl)
placeholder
The placeholder property sets the fallback image to display if the network image fails to load.
BB.AsyncEmblem(
url: imageUrl,
placeholder: Image(systemName: "photo")
)
appearance
The appearance property defines the visual styling of the emblem. Uses the same BB.Emblem.Appearance options.
BB.AsyncEmblem(
url: imageUrl,
appearance: .success
)
layout
The layout property defines the size variant of the emblem. Uses the same BB.Emblem.Layout options.
BB.AsyncEmblem(
url: imageUrl,
layout: .large
)
contentMode
The contentMode property specifies how the image should fit within the view's bounds.
BB.AsyncEmblem(
url: imageUrl,
contentMode: .fill
)
Usage
Basic usage
Create an async emblem with a URL.
import SwiftUI
import BackbaseDesignSystem
let imageUrl = URL(string: "https://example.com/image.png")!
BB.AsyncEmblem(url: imageUrl)
Customizing placeholder and content mode
Provide a custom placeholder and fill content mode.
import SwiftUI
import BackbaseDesignSystem
let customPlaceholder = Image(systemName: "photo")
let imageUrl = URL(string: "https://example.com/image.png")!
BB.AsyncEmblem(
url: imageUrl,
placeholder: customPlaceholder,
contentMode: .fill
)
Using custom appearance and layout
Apply specific appearance and layout options.
import SwiftUI
import BackbaseDesignSystem
let imageUrl = URL(string: "https://example.com/image.png")!
BB.AsyncEmblem(
url: imageUrl,
appearance: .info,
layout: .large
)
Custom image loader implementation
Override the default image loading behavior.
import SwiftUI
import BackbaseDesignSystem
struct CustomImageLoader: BB.AsyncEmblemImageLoader {
func loadImage(from url: URL) async throws -> Image {
// Custom image loading logic here
return Image(systemName: "star")
}
}
// Assign the custom loader
DesignSystem.shared.emblemImageLoader = CustomImageLoader()
States and variants
Loading
While the image is being fetched, a shimmer effect is displayed to indicate loading progress.
Visual characteristics:
- Shimmer animation overlay
- Maintains the specified layout size
- Background color matches the appearance
// Loading state is automatic while fetching
BB.AsyncEmblem(url: imageUrl)
Loaded
When the image loads successfully, it displays within the emblem with the specified styling.
Visual characteristics:
- Fetched image displayed
- Appearance colors applied
- Content mode respected
BB.AsyncEmblem(
url: imageUrl,
appearance: .brand,
contentMode: .fit
)
Failed
When the image fails to load, the placeholder image is displayed instead.
Visual characteristics:
- Placeholder image shown
- Same appearance styling as loaded state
- No error indication
BB.AsyncEmblem(
url: imageUrl,
placeholder: Image(systemName: "photo.fill")
)
Appearance variants
The component supports all BB.Emblem.Appearance options.
|
Appearance |
Description |
|---|---|
|
.brand |
Primary brand colors (default) |
|
.info |
Informational blue tones |
|
.success |
Success green tones |
|
.warning |
Warning yellow/orange tones |
|
.danger |
Error red tones |
|
.category1 - .category10 |
Categorical color schemes |
Size variants
The component supports all BB.Emblem.Layout options.
|
Layout |
Description |
|---|---|
|
.small |
Compact size (40pt) |
|
.medium |
Standard size (48pt, default) |
|
.large |
Larger size (64pt) |
|
.xLarge |
Extra-large size (80pt) |
Customization
Custom image loader
Implement the BB.AsyncEmblemImageLoader protocol to customize how images are fetched.
struct CachedImageLoader: BB.AsyncEmblemImageLoader {
let cache: NSCache<NSURL, UIImage>
func loadImage(from url: URL) async throws -> Image {
if let cached = cache.object(forKey: url as NSURL) {
return Image(uiImage: cached)
}
let (data, _) = try await URLSession.shared.data(from: url)
guard let uiImage = UIImage(data: data) else {
throw URLError(.cannotDecodeContentData)
}
cache.setObject(uiImage, forKey: url as NSURL)
return Image(uiImage: uiImage)
}
}
// Set the custom loader
DesignSystem.shared.emblemImageLoader = CachedImageLoader(cache: .init())
Styling
The component appearance is controlled through the appearance parameter, which uses the same styling as BB.Emblem.
BB.AsyncEmblem(
url: imageUrl,
appearance: .success,
layout: .large
)
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.AsyncEmblem()
.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
Tokens are defined in defaultTokens.json, which is integrated in the bundle of the framework, and can be customized by providing your own theme JSON file.
Token groups used by AsyncEmblem:
- theme.color.emblem: Emblem appearance variant colors (brand, info, success, warning, danger, category-1 to category-10)
Brand appearance tokens (example):
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.emblem.brand.background |
{theme.color.background.brand-subtle} |
|
Foreground |
theme.color.emblem.brand.foreground |
{theme.color.on-background.brand-subtle} |
|
Border |
theme.color.emblem.brand.border |
{theme.color.background.brand-subtle} |
Info appearance tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Background |
theme.color.emblem.info.background |
{theme.color.background.info-subtle} |
|
Foreground |
theme.color.emblem.info.foreground |
{theme.color.on-background.info-subtle} |
Dimension tokens:
|
Token |
JSON Path |
Default Value |
|---|---|---|
|
Radius (small) |
theme.dimension.radius.emblem.sm |
8 |
|
Radius (medium) |
theme.dimension.radius.emblem.md |
12 |
|
Radius (large) |
theme.dimension.radius.emblem.lg |
16 |
|
Radius (xLarge) |
theme.dimension.radius.emblem.xl |
20 |
|
Height (small) |
theme.dimension.height.emblem.sm |
40 |
|
Height (medium) |
theme.dimension.height.emblem.md |
48 |
|
Height (large) |
theme.dimension.height.emblem.lg |
64 |
|
Height (xLarge) |
theme.dimension.height.emblem.xl |
80 |
Semantic tokens
These tokens are accessed via the public DesignSystem.shared API.
|
Token |
API Reference |
Description |
|---|---|---|
|
Colors |
Theme.colors |
Emblem background and foreground colors |
|
Corner Radius |
DesignSystem.shared.cornerRadius |
Emblem corner rounding per layout size |
|
Image Loader |
DesignSystem.shared.emblemImageLoader |
Custom image loading behavior |
See also