Avatar
Images or initials representing people, teams or organizations.
When to use
Use an avatar to identify a person, team or organization with an image or initials. Pair it with a visible name when identity is needed to understand the surrounding content.
Default
Use .avatar for a circle. Give standalone initials an accessible name.
JD
<span class="avatar" role="img" aria-label="John Doe">JD</span>Image
Apply .avatar to an image and use meaningful alternative text when it conveys identity.
<img class="avatar avatar-xl" src="/favicon.svg" alt="Astro" />The class also supports an image wrapper.
<span class="avatar avatar-xl">
<img src="/favicon.svg" alt="Astro" />
</span>Sizes
Sizes are .avatar-sm through .avatar-xl; medium is the default.
JDJDJDJD
<span class="avatar avatar-sm" role="img" aria-label="John Doe">JD</span>
<span class="avatar avatar-md" role="img" aria-label="John Doe">JD</span>
<span class="avatar avatar-lg" role="img" aria-label="John Doe">JD</span>
<span class="avatar avatar-xl" role="img" aria-label="John Doe">JD</span>Square
Add .avatar-square for a rounded square.
JD
<span class="avatar avatar-lg avatar-square bg-primary" role="img" aria-label="John Doe"> JD </span>Accessibility and behavior
- Give informative images meaningful
alttext. Use empty alternative text or hide the avatar when adjacent text already identifies the same person. - For standalone initials, use an image role with an accessible name, for example
<span class="avatar" role="img" aria-label="John Doe">JD</span>. - An avatar is a visual, not an action. Put it inside a native link or button when it should navigate or open a profile, and name that control.
CSS variables
Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--avatar-size | 2.5rem | Width and height; size modifiers replace this value. | .avatar |
--avatar-border-radius | 50% | Shape of the avatar; square avatars use the shared radius. | .avatar |
--avatar-bg-color | var(--bg-highlight) | Background color. | .avatar |
--avatar-color | var(--text-color) | Text and icon color. | .avatar |
--avatar-border-width | 0 | Border thickness. | .avatar |
--avatar-border-color | transparent | Border color. | .avatar |
--avatar-font-size | var(--font-size-sm) | Text size. | .avatar |
--avatar-font-weight | 700 | Text weight. | .avatar |
--avatar-image-fit | cover | How the image fills its bounds (object-fit). | .avatar |
--avatar-image-position | center | Image crop alignment (object-position). | .avatar |