Avatar

A compact visual representation of a user. An avatar shows the person's image when available, gracefully falling back to their initial, then to a neutral ? placeholder — so it always renders something sensible even with missing data.

Use avatars wherever you need to identify a person at a glance: comment threads, member lists, navigation bars, profile headers, and assignee indicators.

Usage

The only thing an avatar needs is a name (used for the initial fallback and as the image's alt text). Pass a src to show a photo.

BasicAn avatar with an image and a name.

<script setup lang="ts">
import { Avatar } from "@dlbcodes/ui";
</script>

<template>
    <Avatar src="https://i.pravatar.cc/120?img=12" name="Ana Silva" />
</template>

Fallbacks

When no src is provided — or the image fails to load — the avatar shows the first character of name. This means you can render avatars for users who haven't uploaded a photo, or whose photo URL is broken, without any extra handling. If the src changes later, the avatar tries the new image again.

With no name either, it shows a ?.

Initial fallbackNo image: the first letter of the name is shown.

<script setup lang="ts">
import { Avatar } from "@dlbcodes/ui";
</script>

<template>
    <div class="flex items-center gap-4">
        <Avatar name="Ana Silva" />
        <Avatar name="Bruno Costa" />
        <Avatar name="carla dias" />
    </div>
</template>

Sizes

Fourteen sizes are available via the size prop, from xs to 10xl. base is the default.

Size	Dimensions
xs	24px
sm	32px
base	40px
lg	48px
xl	56px
2xl	64px
3xl – 9xl	72px – 120px, in 8px steps
10xl	120px, growing to 160px on wide screens (xl breakpoint)

The heights of sm, base, lg and xl match the button and input sizes of the same name, so an avatar lines up next to them. From 3xl up, the image sits inside a padded frame.

Sizesxs through xl.

<script setup lang="ts">
import { Avatar } from "@dlbcodes/ui";
</script>

<template>
    <div class="flex items-center gap-4">
        <Avatar name="A" size="sm" />
        <Avatar name="A" size="base" />
        <Avatar name="A" size="lg" />
    </div>
</template>

Corner radius

The avatar's corners come from the theme's --radius token, so it follows your radius setting like every other component. The image's own corners are kept concentric with the frame at any radius.

Customizing

Every avatar accepts a class prop that merges onto the root element, so you can add a ring or adjust spacing without touching the component. This is the primary extension point — reach for it before wrapping the component.

To change the shape, override the frame and its inner element, or the image keeps the theme's corners inside your new frame:

vue

<!-- a circle -->
<Avatar name="Ana Silva" class="rounded-full *:rounded-full" />

<!-- a square -->
<Avatar name="Ana Silva" class="rounded-none *:rounded-none" />

Custom shape and ringA circular avatar, and one with a brand-colored ring.

<script setup lang="ts">
import { Avatar } from "@dlbcodes/ui";
</script>

<template>
    <div class="flex items-center gap-4">
        <!-- The `class` prop merges onto the root — override shape, ring, etc. -->
        <Avatar name="Ana Silva" class="rounded-lg" />
        <Avatar
            src="https://i.pravatar.cc/120?img=5"
            name="Bruno Costa"
            class="ring-2 ring-brand-200 ring-offset-2 ring-offset-bg-base"
        />
    </div>
</template>

Avatar group

Avatars compose into an overlapping stack with a little negative margin and a ring to separate them — handy for showing a set of collaborators. The last item can be an initials-only avatar acting as an overflow count.

GroupAn overlapping stack with an overflow count.

<script setup lang="ts">
import { Avatar } from "@dlbcodes/ui";
</script>

<template>
    <!-- A simple overlapping stack using negative margin + a ring to separate. -->
    <div class="flex -space-x-3">
        <Avatar
            src="https://i.pravatar.cc/120?img=1"
            name="A"
            class="ring-2 ring-bg-base"
        />
        <Avatar
            src="https://i.pravatar.cc/120?img=2"
            name="B"
            class="ring-2 ring-bg-base"
        />
        <Avatar
            src="https://i.pravatar.cc/120?img=3"
            name="C"
            class="ring-2 ring-bg-base"
        />
        <Avatar name="+5" class="ring-2 ring-bg-base" />
    </div>
</template>

Props

Prop	Type	Default	Description
name	string | null	null	The person's name. Its first character is the fallback when there's no image, and it's used as the image's alt text for accessibility.
src	string | null	null	Image URL. When present (and it loads), the photo is shown; otherwise the avatar falls back to the initial.
size	"xs" | "sm" | "base" | "lg" | "xl" | "2xl" … "10xl"	"base"	The avatar's size. See the table above.
class	string	—	Classes merged onto the root element. Use this to add a ring, adjust layout, or change shape (see above).

Accessibility

• With an image, the alt text is set from name, so screen readers announce who the avatar represents. With no name, the alt is empty and the image is skipped, since there's nothing meaningful to announce.
• The initial fallback is exposed as an image labelled with name, so a screen reader says the person's name instead of a lone letter. With no name, the ? placeholder is hidden from assistive technology.
• Keep name meaningful (the full name) rather than passing initials directly.