Identity and Avatars

Fixed-size avatar primitives for initials, images, shape variants, and overlapping groups.

Avatars represent a person, team, or account in a compact visual region. Use <user-avatar>, [data-avatar], or .avatar; all three hosts share the same size, shape, image, and theming contract.

Sizes and host forms

The default avatar is 2.75rem. Use size="sm" for dense interfaces and size="lg" for prominent identity surfaces. Its inline and block dimensions are invariant, so a flex or grid parent cannot compress the circle into an oval.

<layout-cluster gap="var(--space-lg)" align="center">
  <user-avatar size="sm" aria-label="Ada Lovelace">AL</user-avatar>
  <span data-avatar="true" aria-label="Grace Hopper">GH</span>
  <span class="avatar" size="lg" aria-label="Katherine Johnson">KJ</span>
</layout-cluster>

<user-avatar size="sm" aria-label="Ada Lovelace">AL</user-avatar>
<span data-avatar aria-label="Grace Hopper">GH</span>
<span class="avatar" size="lg" aria-label="Katherine Johnson">KJ</span>

Circle and square shapes

Circle is the default. shape="square" uses the shared medium radius while preserving the same square footprint.

<layout-cluster gap="var(--space-lg)" align="center">
  <user-avatar size="lg" aria-label="Round account avatar">RA</user-avatar>
  <user-avatar size="lg" shape="square" aria-label="Square organization avatar">SO</user-avatar>
</layout-cluster>

Image and initials fallback

An img or picture child fills the avatar and uses object-fit: cover. Keep meaningful identity in the image alt; use an empty alt only when nearby text already names the person.

Image avatar with initials fallback

Reset preview

Preview Code

GH

Avatar groups

<avatar-group>, [data-avatar-group], and .avatar-group overlap direct avatar children while adding a surface-colored separation ring.

<avatar-group aria-label="Project members">
  <user-avatar aria-label="Ada Lovelace">AL</user-avatar>
  <user-avatar aria-label="Grace Hopper">GH</user-avatar>
  <user-avatar aria-label="Katherine Johnson">KJ</user-avatar>
  <user-avatar aria-label="Margaret Hamilton">MH</user-avatar>
</avatar-group>

Give the group a useful accessible label. Each avatar should retain its own name when the individual identities matter.

Stable sizing in flexible layouts

The avatar owns a fixed flex basis, minimum inline size, minimum block size, and square aspect ratio. The adjacent content receives the flexible space.

<article class="example-panel">
  <flex align="flex-start" gap="var(--space-md)">
    <user-avatar size="lg" aria-label="Avery Gray">AG</user-avatar>
    <div grow="1" basis="0">
      <h3 style="margin-block-start: 0">Avery Gray</h3>
      <p class="example-muted">A long account description can wrap onto several lines without borrowing width from the identity marker.</p>
    </div>
    <button type="button" shrink="0">Follow</button>
  </flex>
</article>

Tokens

• --avatar-size
• --avatar-radius
• --avatar-background and --avatar-color
• --avatar-border-width and --avatar-border-color
• --avatar-image-fit
• --avatar-font-weight
• --avatar-group-overlap
• --avatar-group-ring-width and --avatar-group-ring-color

Prefer initials or a meaningful image instead of decorative icons. When initials are the only visible content, add aria-label with the complete identity.