Provide a meaningful
label for every avatar. When an image is used, add alt-text and keep initials short so they remain a clean fallback if the image cannot load.When to use
Use avatars when
- People need to identify a person, team, or brand quickly
- A list, card, or thread benefits from a compact visual identifier
- A profile image or initials add useful context without extra text
Do not use avatars when
- Identity is not relevant to the task or content
- A dense layout would become noisy with extra visuals
- Text labels alone already make ownership or authorship obvious
Avatar patterns
These are the most common contexts where avatars add meaningful value. Use them as a reference when deciding whether an avatar fits the layout.Contact details
Pair an avatar with a name and supporting metadata when identity is central to the content, such as profile summaries or directory entries.
List
Use avatars in dense lists when a quick visual cue helps people scan authors, owners, assignees, or participants faster.
Contact card
Add an avatar to card-based layouts when the card represents a person, team, or brand and identity should be immediately recognizable.
Select user
Use avatars in selection patterns when people need to choose from multiple users and benefit from both a name and a visual identifier.
Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Base | The visible avatar surface (base part) |
| 2 | Visual | The displayed image (img part) or initials (text part) |
| 3 | Badge | Optional content placed in the badge slot |
Design guidelines
Shape
Initials
Pass the full intended initials (e.g."JD" for John Doe) and let the component handle trimming. The component automatically caps the visible characters based on size:
Image and initials together
Always pass both
image and initials when showing a photo. If the image fails to load, the component automatically falls back to the initials — no extra logic required on your side.Usage
Avatar supports two primary variants:Text for initials and Image for profile photos or logos.
Text
Use initials when no uploaded image is available or when the interface is intentionally compact. Pass short values rather than full names; the component trims the visible text based on the selectedsize.
Image
When a profile photo or logo is available, pass bothimage and initials. The image is shown first, while initials remain a built-in fallback if the image fails to load.
Options
Shape and size
Avatar supports four sizes (xsmall, small, medium, large) and two shapes (circle, square). Choose size based on context: small works well in dense lists and inline layouts; large suits profile headers and contact cards where identity is the focal point. Keep shape and size consistent within the same group so the UI feels intentional and easy to scan.
Avatar group
Use a grouped avatar pattern when you need to represent multiple participants in a compact space, such as shared ownership, collaborators, or team members. Keep the same size and shape across the whole group.With badge
Use thebadge slot when the avatar needs a compact status or count indicator. bq-badge is the most common choice.
Best practices
DoUse the supported
shape options to keep avatars aligned with the system and the surrounding UI.Don’tDo not resize avatars outside the available sizes. It can distort the component and break visual consistency.
DoKeep initials short, ideally using the first letters of a first and last name so they remain legible at every size.
Don’tDo not pass full names as initials. Long strings quickly become unreadable and visually unbalanced.
DoKeep avatar style consistent within the same group. Use the same shape, size, and image-vs-initials pattern where possible.
Don’tDo not mix mismatched avatar treatments in one group unless the difference carries meaning. It makes lists harder to scan.
DoUse well-cropped images that fit the avatar area cleanly and keep the subject centered and recognizable.
Don’tDo not use clipped, stretched, or low-quality images. If the image is not clear, initials are often the better fallback.
Accessibility
The component automatically appliesrole="img" and aria-label to its root element. You do not need to add ARIA attributes manually — provide a descriptive label and the component handles the rest.
When the avatar displays an image, also pass alt-text to describe what the image shows. Keep initials short so the text fallback remains readable if the image cannot load.
If the avatar appears alongside other interactive elements such as names, links, or buttons, make sure the surrounding pattern is accessible as a whole — the avatar’s built-in label describes the avatar itself, not the composite component around it.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
altText | alt-text | Alternate text applied to the internal image element | string | undefined |
image | image | Image source to display inside the avatar | string | undefined |
initials | initials | Short text shown when no image is visible | string | undefined |
label | label | Accessible name announced for the avatar | string | undefined |
shape | shape | Visual shape of the avatar | 'circle' | 'square' | 'circle' |
size | size | Size of the avatar | 'xsmall' | 'small' | 'medium' | 'large' | 'medium' |
Slots
| Slot | Description |
|---|---|
badge | Optional badge content positioned on the avatar edge |
Shadow parts
| Part | Description |
|---|---|
base | The visible avatar wrapper |
img | The internal <img> element |
text | The initials text element |
badge | The container wrapping the badge slot |
CSS custom properties
Resources
Interactive playground
Explore avatar variants and states in Storybook
Source code
View the component source on GitHub