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
HTML
<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.

Astro
HTML
<img class="avatar avatar-xl" src="/favicon.svg" alt="Astro" />

The class also supports an image wrapper.

Astro
HTML
<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
HTML
<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
HTML
<span class="avatar avatar-lg avatar-square bg-primary" role="img" aria-label="John Doe"> JD </span>

Accessibility and behavior

  • Give informative images meaningful alt text. 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.

TokenDefaultPurposeScope / state
--avatar-size2.5remWidth and height; size modifiers replace this value..avatar
--avatar-border-radius50%Shape of the avatar; square avatars use the shared radius..avatar
--avatar-bg-colorvar(--bg-highlight)Background color..avatar
--avatar-colorvar(--text-color)Text and icon color..avatar
--avatar-border-width0Border thickness..avatar
--avatar-border-colortransparentBorder color..avatar
--avatar-font-sizevar(--font-size-sm)Text size..avatar
--avatar-font-weight700Text weight..avatar
--avatar-image-fitcoverHow the image fills its bounds (object-fit)..avatar
--avatar-image-positioncenterImage crop alignment (object-position)..avatar