Skip to content
WeDanceDocs
Componentsbeta

Avatar

A face for a teacher, DJ or dancer — or a mark for a venue. Shows the photo when it loads, initials when it doesn’t.

Demo

LLisandra
OOsmel
SSilvio
IIvana
vue
<Avatar class="text-secondary-foreground">
  <AvatarImage src="/people/lisandra.jpg" alt="Lisandra" />
  <AvatarFallback>L</AvatarFallback>
</Avatar>

Fallback

When there is no photo, or it fails to load, AvatarFallback shows. Use the first letter of the first and last name.

AEBKWDBroken image → initials
vue
<!-- text-secondary-foreground: cream initials on the amber fallback (see Accessibility) -->
<Avatar class="text-secondary-foreground">
  <AvatarImage :src="teacher.photo" :alt="teacher.name" />
  <AvatarFallback>AE</AvatarFallback>
</Avatar>

Sizes

Three sizes. sm is the default.

Osm
Obase
Olg
vue
<Avatar size="sm">…</Avatar>    <!-- 40px — lists, comments, attendee stacks -->
<Avatar size="base">…</Avatar>  <!-- 64px — teacher cards -->
<Avatar size="lg">…</Avatar>    <!-- 128px — profile header -->

Shape

Circles for people. Squares for venues, schools and organisers, so the two never get confused in a list.

SSilvio · teacher
LRLa Rumba · venue
vue
<!-- People are circles; venues and organisations are squares -->
<Avatar shape="square" class="text-secondary-foreground font-bold">
  <AvatarFallback>LR</AvatarFallback>
</Avatar>

Who’s going

Overlap small avatars with a card-coloured ring to show attendees.

vue
<div class="flex -space-x-2">
  <Avatar v-for="t in going" :key="t.name" class="ring-2 ring-card text-secondary-foreground">
    <AvatarImage :src="t.src" :alt="t.name" />
    <AvatarFallback>{{ t.initials }}</AvatarFallback>
  </Avatar>
</div>

Props

PropTypeDefaultDescription
size'sm' | 'base' | 'lg''sm'Avatar. 40 / 64 / 128px. Fallback text scales with it (xs / 2xl / 5xl).
shape'circle' | 'square''circle'Avatar. Circle for people, square (rounded-md) for venues, schools and organisers.
classHTMLAttributes["class"]—Avatar. Merged with cn() — use for rings in stacks or a custom background.
srcstring—AvatarImage. Image URL. Shown only once it has loaded; until then (or on error) the fallback shows.
altstring—AvatarImage. The person’s name, or "" when the name is printed right next to it.
delayMsnumber—AvatarFallback. Wait before showing the fallback, to avoid an initials flash on fast connections.

Do & don't

I

Do — Always pair an image with a fallback, so a slow or broken photo still shows who it is.

Don't — AvatarImage alone. If the photo fails you get an empty amber circle that says nothing.

Accessibility

  • Give AvatarImage an alt with the person’s name. When the name is already printed next to the avatar, use alt="" so screen readers don’t read it twice.
  • Fallback initials are read aloud as letters. If the avatar stands alone (an attendee stack), add an aria-label or visually hidden name on the wrapper — “Lisandra, Osmel and 12 others going”.
  • Known issue: the default fallback is dark brown text-foreground on amber bg-secondary — about 2.5:1, below WCAG AA. Until the component default is fixed, add class="text-secondary-foreground" to Avatar wherever initials can show (cream on amber, ~5.4:1), as the examples on this page do.
  • Avatars are not buttons. If tapping opens a profile, wrap the avatar and the name in one link.