Components / Display

Avatar

An image that shows your fallback content while loading or when the image fails.

Preview

Use cases

Team directory

Display a person’s image alongside their name and role.

Participant list

Show initials immediately while remote profile images load.

Usage example

Vue

<script setup lang="ts">
import Avatar from './components/ui/avatar/Avatar.vue'
import AvatarFallback from './components/ui/avatar/AvatarFallback.vue'
import AvatarImage from './components/ui/avatar/AvatarImage.vue'
</script>

<template>
  <Avatar size="lg">
    <AvatarImage src="/avatar.png" alt="Ada Lovelace" />
    <AvatarFallback aria-hidden="true">AL</AvatarFallback>
  </Avatar>
</template>

More examples

Named team member

The image and text together identify the person.

Named team member

<script setup lang="ts">
import Avatar from './components/ui/avatar/Avatar.vue'
import AvatarFallback from './components/ui/avatar/AvatarFallback.vue'
import AvatarImage from './components/ui/avatar/AvatarImage.vue'
</script>

<template>
  <div class="flex items-center gap-3">
    <Avatar><AvatarImage src="/team/ada.jpg" alt="" /><AvatarFallback aria-hidden="true">AL</AvatarFallback></Avatar>
    <span>Ada Lovelace, engineer</span>
  </div>
</template>

Rounded project image

Use a non-circular shape for an entity such as a project.

Rounded project image

<script setup lang="ts">
import Avatar from './components/ui/avatar/Avatar.vue'
import AvatarFallback from './components/ui/avatar/AvatarFallback.vue'
import AvatarImage from './components/ui/avatar/AvatarImage.vue'
</script>

<template>
  <Avatar shape="rounded" size="lg">
    <AvatarImage src="/projects/atlas.png" alt="Atlas project" />
    <AvatarFallback>AT</AvatarFallback>
  </Avatar>
</template>

Key API

The most useful props, models, slots, events, and methods for this component.

Key API for Avatar
Name	Type	Default or requirement
`size`	sm \| md \| lg	md
`shape`	circle \| rounded \| square	circle
`AvatarImage src`	string	required
`AvatarImage alt`	string	required
`AvatarFallback default`	slot	required

The fallback remains visible until the image loads and after errors. Use meaningful alt text, or alt="" for decorative images; hide a fallback that repeats adjacent text from assistive technology.

Implementation notes

The fallback is shown while the image loads and if loading fails.
Use stable initials or a short project abbreviation as the fallback.

Accessibility and localization

Use alt="" when adjacent text already names the same person; use descriptive alt when the image is the only identifier.