Available from v1.2.0
Avatar
Avatar is a circular view component that displays a user's profile image, initials, or a placeholder icon.
Platform availability: iOS 17.0+
When to use:
- Use Avatar when you need to visually represent a user, contact, or entity in lists, headers, or profile sections.
It includes the following features:
- Displays profile images, initials, or placeholder icons.
- Multiple size options (small, default, large).
- Customizable icon and initials colors.
- Disabled state with configurable background color.
Import
import BackbaseDesignSystem
Visual reference
|
|
|
|
|
API reference
Avatar
A circular view component that displays a user's profile image, initials, or a placeholder icon.
Properties
|
Property |
Type |
Description |
|---|---|---|
|
iconColor |
UIColor |
The tint color of the icon inside the avatar view |
|
initialsColor |
UIColor |
The color of the initials label inside the avatar view |
|
size |
AvatarSize |
The size of the view. Options: .small, .default, or .large |
|
image |
UIImage? |
The image to display. Defaults to nil |
|
initials |
String? |
The initials string to display when image is not set. Maximum 2 characters |
|
disabledBackgroundColor |
UIColor |
The background color for the disabled state |
AvatarSize
|
Case |
Description |
|---|---|
|
.small |
Small avatar size |
|
.default |
Default avatar size |
|
.large |
Large avatar size |
Configuration
|
Property |
Type |
Default |
|---|---|---|
|
size |
AvatarSize |
.default |
|
image |
UIImage? |
nil |
|
initials |
String? |
nil |
|
iconColor |
UIColor |
Neutral 80 dark |
|
initialsColor |
UIColor |
Text default light |
size
The size property controls the dimensions of the avatar. Three preset sizes are available.
let avatar = Avatar()
avatar.size = .large
image
The image property sets a profile image. When set, this takes precedence over initials.
let avatar = Avatar()
avatar.image = UIImage(named: "profile")
initials
The initials property displays up to 2 characters when no image is set.
let avatar = Avatar()
avatar.initials = "JD"
Usage
Basic usage
let avatar = Avatar()
avatar.image = UIImage(named: "profile")
With initials
let avatar = Avatar()
avatar.initials = "JD"
With custom size
let avatar = Avatar()
avatar.size = .large
avatar.initials = "AB"
With custom colors
let avatar = Avatar()
avatar.initials = "XY"
avatar.initialsColor = Theme.colors.foreground.brand
States and variants
Image variant
Displays a profile image.
Visual characteristics:
- Circular clipped image
- Aspect fill content mode
let avatar = Avatar()
avatar.image = UIImage(named: "user-photo")
Initials variant
Displays up to 2 characters when no image is available.
Visual characteristics:
- Circular background
- Centered text
let avatar = Avatar()
avatar.initials = "JD"
Icon variant
Displays a placeholder icon when neither image nor initials are set.
Visual characteristics:
- Default placeholder icon
- Circular background
let avatar = Avatar()
// Icon is displayed by default when no image or initials are set
Size variants
|
Size |
Description |
|---|---|
|
.small |
Compact size for dense layouts |
|
.default |
Standard size for most use cases |
|
.large |
Prominent size for profile headers |
let smallAvatar = Avatar()
smallAvatar.size = .small
let largeAvatar = Avatar()
largeAvatar.size = .large
Customization
Custom icon color
let avatar = Avatar()
avatar.iconColor = Theme.colors.foreground.brand
Custom initials color
let avatar = Avatar()
avatar.initials = "AB"
avatar.initialsColor = .systemBlue
Disabled state
let avatar = Avatar()
avatar.disabledBackgroundColor = Theme.colors.background.disabled
avatar.isUserInteractionEnabled = false
Accessibility
The Avatar component is built with accessibility in mind. See the information below for supported behaviors and configuration options to ensure a fully accessible experience for all users.
Accessibility configuration
|
Property |
Description |
Type |
|---|---|---|
|
accessibilityLabel |
The descriptive label for the avatar |
String? |
|
isAccessibilityElement |
Whether the avatar is an accessibility element |
Bool |
Best practices
- Set an appropriate accessibilityLabel that describes the user or entity
- Include the person's name in the accessibility label when available
- For decorative avatars, set isAccessibilityElement to false
let avatar = Avatar()
avatar.accessibilityLabel = "User profile picture"
Dependencies
- External dependencies: None
- Internal dependencies: None
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 |
|---|---|---|
|
Background |
Theme.colors.background.brandSubtle |
Avatar background color |
|
Foreground |
Theme.colors.foreground.brand |
Brand foreground color |
|
Icon Color |
Theme.colors.neutrals.neutral80 |
Icon tint color |
|
Initials Color |
Theme.colors.text.default |
Initials text color |
|
Typography |
DesignSystem.shared.fonts |
Initials font |
|
Disabled Background |
Theme.colors.surfaceDisabled.default |
Disabled state background |