Import
Jetpack Compose framework
Before you can use components from the Backbase Design System SDK, make sure you've installed the package and import it at the top of your file.
import com.backbase.android.design.component.AsyncEmblem
import com.backbase.android.design.component.EmblemLayout
import com.backbase.android.design.component.EmblemLayouts
import com.backbase.android.design.component.EmblemColorScheme
import com.backbase.android.design.component.EmblemColorSchemes
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.painter.Painter
import androidx.compose.ui.layout.ContentScale
import androidx.compose.ui.unit.dp
Usage
Basic usage
Create an AsyncEmblem to load and display images from URLs with automatic state management.
AsyncEmblem(
url = "https://example.com/image.png",
contentDescription = "Company logo"
)
Custom layout and styling
Use AsyncEmblem with custom layout sizes and color schemes for different visual contexts.
AsyncEmblem(
url = "https://example.com/profile.jpg",
contentDescription = "User profile",
layout = EmblemLayouts.lg,
placeholderColorScheme = EmblemColorSchemes.brand
)
Configuration
|
Parameter |
Type |
Default |
|---|---|---|
|
contentDescription |
String? |
Required |
|
contentScale |
ContentScale |
ContentScale.Fit |
|
layout |
EmblemLayout |
EmblemLayouts.md |
|
modifier |
Modifier |
Modifier |
|
placeholderColorScheme |
EmblemColorScheme |
EmblemColorSchemes.neutral |
|
placeholderPainter |
Painter |
Icons.Painter.iconShoppingBag |
|
url |
String |
Required |
contentDescription
The contentDescription parameter provides accessibility information for screen readers when describing the image content.
AsyncEmblem(
url = "https://example.com/badge.png",
contentDescription = "Verified account badge"
)
contentScale
The contentScale parameter defines how the loaded image scales within the emblem bounds.
AsyncEmblem(
url = "https://example.com/image.png",
contentDescription = "Scaled image",
contentScale = ContentScale.Crop
)
layout
The layout parameter determines the size and shape of the emblem container.
AsyncEmblem(
url = "https://example.com/icon.png",
contentDescription = "Large icon",
layout = EmblemLayouts.xl
)
modifier
The modifier parameter allows custom layout and styling modifications to the emblem.
AsyncEmblem(
url = "https://example.com/image.png",
contentDescription = "Custom styled emblem",
modifier = Modifier.padding(16.dp)
)
placeholderColorScheme
The placeholderColorScheme parameter sets the color scheme used when displaying the placeholder in error states.
AsyncEmblem(
url = "https://example.com/image.png",
contentDescription = "Error state emblem",
placeholderColorScheme = EmblemColorSchemes.danger
)
placeholderPainter
The placeholderPainter parameter defines the fallback image displayed when the URL fails to load.
AsyncEmblem(
url = "https://example.com/image.png",
contentDescription = "Custom placeholder",
placeholderPainter = Icons.Painter.iconPerson
)
url
The url parameter specifies the image URL to load asynchronously.
AsyncEmblem(
url = "https://cdn.example.com/user-avatar.jpg",
contentDescription = "User avatar"
)
Loading states
Automatic state management
The AsyncEmblem automatically manages loading and error states based on the image loading progress.
// Component automatically shows:
// - Shimmer animation during loading
// - Placeholder with error styling on failure
// - Actual image when successfully loaded
AsyncEmblem(
url = "https://example.com/dynamic-image.png",
contentDescription = "Dynamic content"
)
Loading state behavior
During loading, the component displays a shimmer animation with the emblem's shape and size.
// Loading state shows shimmer background
AsyncEmblem(
url = "https://slow-loading-image.com/image.png",
contentDescription = "Loading image",
layout = EmblemLayouts.lg
)
Error state behavior
When image loading fails, the component displays the placeholder painter with the specified color scheme.
// Error state shows placeholder with color scheme styling
AsyncEmblem(
url = "https://invalid-url.com/missing.png",
contentDescription = "Failed to load",
placeholderPainter = Icons.Painter.iconError,
placeholderColorScheme = EmblemColorSchemes.danger
)
Layout options
EmblemLayouts
The EmblemLayouts object provides predefined size configurations:
- sm: Small emblem size
- md: Medium emblem size (default)
- lg: Large emblem size
- xl: Extra large emblem size
// Different layout sizes
AsyncEmblem(url = "https://example.com/small.png", contentDescription = "Small", layout = EmblemLayouts.sm)
AsyncEmblem(url = "https://example.com/medium.png", contentDescription = "Medium", layout = EmblemLayouts.md)
AsyncEmblem(url = "https://example.com/large.png", contentDescription = "Large", layout = EmblemLayouts.lg)
AsyncEmblem(url = "https://example.com/xlarge.png", contentDescription = "Extra Large", layout = EmblemLayouts.xl)
Color schemes
EmblemColorSchemes
The EmblemColorSchemes object provides predefined color configurations:
- brand: Brand colors for primary branding
- neutral: Neutral colors for general use
- info: Information state colors
- success: Success state colors
- warning: Warning state colors
- danger: Error/danger state colors
- category1 through category10: Category-specific colors
// Different color schemes
AsyncEmblem(url = "https://example.com/brand.png", contentDescription = "Brand", placeholderColorScheme = EmblemColorSchemes.brand)
AsyncEmblem(url = "https://example.com/success.png", contentDescription = "Success", placeholderColorScheme = EmblemColorSchemes.success)
AsyncEmblem(url = "https://example.com/category.png", contentDescription = "Category", placeholderColorScheme = EmblemColorSchemes.category1)
Design tokens
The AsyncEmblem component uses design tokens for consistent styling:
- Colors: Color schemes use semantic design tokens for consistent theming
- Layout: Size and shape configurations follow design system spacing
- Animation: Shimmer loading animation uses design system patterns
- Typography: Inherits text styling for accessibility descriptions
// Component automatically applies design system styling through EmblemLayouts and EmblemColorSchemes
AsyncEmblem(
url = "https://example.com/themed-image.png",
contentDescription = "Themed emblem",
layout = EmblemLayouts.md,
placeholderColorScheme = EmblemColorSchemes.neutral
)