Avatar

Display user profile images with fallback support for missing images.

An image element with a fallback for representing a user. Built on a native <img>, enhanced by a small Stimulus controller: the fallback is shown until the image successfully loads, so a missing avatar, a slow network or a broken URL always resolve to the fallback instead of a broken image icon.

NL AD

NL JL AD

<div class="flex flex-row flex-wrap items-center gap-6 md:gap-12">
    <twig:ui:Avatar>
        <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps"/>
        <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
    <twig:ui:Avatar>
        <twig:ui:Avatar:Image src="https://avatars.laravel.cloud/168544b7-8325-4ac9-a019-5316d1824b0e?vibe=forest" alt="Alex Doe" />
        <twig:ui:Avatar:Fallback>AD</twig:ui:Avatar:Fallback>
        <twig:ui:Avatar:Badge class="bg-green-500 dark:bg-green-600" />
    </twig:ui:Avatar>
    <twig:ui:Avatar:Group>
        <twig:ui:Avatar>
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
        </twig:ui:Avatar>
        <twig:ui:Avatar>
            <twig:ui:Avatar:Image src="https://avatars.laravel.cloud/1a5e26e9-6894-40fd-b37f-75286143c505?vibe=ocean" alt="Jamie Lee" />
            <twig:ui:Avatar:Fallback>JL</twig:ui:Avatar:Fallback>
        </twig:ui:Avatar>
        <twig:ui:Avatar>
            <twig:ui:Avatar:Image src="https://avatars.laravel.cloud/168544b7-8325-4ac9-a019-5316d1824b0e?vibe=forest" alt="Alex Doe" />
            <twig:ui:Avatar:Fallback>AD</twig:ui:Avatar:Fallback>
        </twig:ui:Avatar>
        <twig:ui:Avatar:GroupCount>+3</twig:ui:Avatar:GroupCount>
    </twig:ui:Avatar:Group>
</div>

Usage

<twig:ui:Avatar>
    <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
    <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
</twig:ui:Avatar>

Examples

Fallback

The <twig:ui:Avatar:Fallback> content, usually initials or an icon, stays visible until the image finishes loading. It is also what renders when <twig:ui:Avatar:Image> is omitted entirely.

<div class="flex flex-wrap items-center gap-2">
    <twig:ui:Avatar>
        <twig:ui:Avatar:Image src="https://broken.example/avatar.png" alt="Jane Doe" />
        <twig:ui:Avatar:Fallback>JD</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
    <twig:ui:Avatar>
        <twig:ui:Avatar:Fallback>
            <twig:ux:icon name="lucide:user" />
        </twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
</div>

Badge

Use <twig:ui:Avatar:Badge> to add a status indicator at the bottom-right of the avatar.

<twig:ui:Avatar>
    <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
    <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
    <twig:ui:Avatar:Badge class="bg-green-500 dark:bg-green-600" />
</twig:ui:Avatar>

Badge with icon

<twig:ui:Avatar>
    <twig:ui:Avatar:Image src="https://avatars.laravel.cloud/32bd7432-c01d-41c1-a368-059b9dde98cf?vibe=daybreak" alt="Sam Rivera" />
    <twig:ui:Avatar:Fallback>SR</twig:ui:Avatar:Fallback>
    <twig:ui:Avatar:Badge>
        <twig:ux:icon name="lucide:plus" />
    </twig:ui:Avatar:Badge>
</twig:ui:Avatar>

Badge position

Move the badge to any corner with position. The badge always scales with the avatar's own size, shown here for every size.

NL NL NL NL

<div class="flex flex-col gap-6">
    <div class="flex flex-wrap items-center gap-6">
        <twig:ui:Avatar size="xs">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="top-start" class="bg-amber-500 dark:bg-amber-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar size="xs">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="top-end" class="bg-blue-500 dark:bg-blue-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar size="xs">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="bottom-start" class="bg-red-500 dark:bg-red-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar size="xs">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="bottom-end" class="bg-green-500 dark:bg-green-600" />
        </twig:ui:Avatar>
    </div>
    <div class="flex flex-wrap items-center gap-6">
        <twig:ui:Avatar size="sm">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="top-start" class="bg-amber-500 dark:bg-amber-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar size="sm">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="top-end" class="bg-blue-500 dark:bg-blue-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar size="sm">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="bottom-start" class="bg-red-500 dark:bg-red-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar size="sm">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="bottom-end" class="bg-green-500 dark:bg-green-600" />
        </twig:ui:Avatar>
    </div>
    <div class="flex flex-wrap items-center gap-6">
        <twig:ui:Avatar>
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="top-start" class="bg-amber-500 dark:bg-amber-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar>
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="top-end" class="bg-blue-500 dark:bg-blue-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar>
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="bottom-start" class="bg-red-500 dark:bg-red-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar>
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="bottom-end" class="bg-green-500 dark:bg-green-600" />
        </twig:ui:Avatar>
    </div>
    <div class="flex flex-wrap items-center gap-6">
        <twig:ui:Avatar size="lg">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="top-start" class="bg-amber-500 dark:bg-amber-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar size="lg">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="top-end" class="bg-blue-500 dark:bg-blue-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar size="lg">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="bottom-start" class="bg-red-500 dark:bg-red-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar size="lg">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="bottom-end" class="bg-green-500 dark:bg-green-600" />
        </twig:ui:Avatar>
    </div>
    <div class="flex flex-wrap items-center gap-6">
        <twig:ui:Avatar size="xl">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="top-start" class="bg-amber-500 dark:bg-amber-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar size="xl">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="top-end" class="bg-blue-500 dark:bg-blue-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar size="xl">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="bottom-start" class="bg-red-500 dark:bg-red-600" />
        </twig:ui:Avatar>
        <twig:ui:Avatar size="xl">
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
            <twig:ui:Avatar:Badge position="bottom-end" class="bg-green-500 dark:bg-green-600" />
        </twig:ui:Avatar>
    </div>
</div>

Group

Use <twig:ui:Avatar:Group> to stack a set of avatars with overlap.

NL JL AD

<twig:ui:Avatar:Group>
    <twig:ui:Avatar>
        <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
        <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
    <twig:ui:Avatar>
        <twig:ui:Avatar:Image src="https://avatars.laravel.cloud/1a5e26e9-6894-40fd-b37f-75286143c505?vibe=ocean" alt="Jamie Lee" />
        <twig:ui:Avatar:Fallback>JL</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
    <twig:ui:Avatar>
        <twig:ui:Avatar:Image src="https://avatars.laravel.cloud/168544b7-8325-4ac9-a019-5316d1824b0e?vibe=forest" alt="Alex Doe" />
        <twig:ui:Avatar:Fallback>AD</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
</twig:ui:Avatar:Group>

Group count

Add <twig:ui:Avatar:GroupCount> at the end of a group to show how many more members aren't displayed.

NL JL AD

<twig:ui:Avatar:Group>
    <twig:ui:Avatar>
        <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
        <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
    <twig:ui:Avatar>
        <twig:ui:Avatar:Image src="https://avatars.laravel.cloud/1a5e26e9-6894-40fd-b37f-75286143c505?vibe=ocean" alt="Jamie Lee" />
        <twig:ui:Avatar:Fallback>JL</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
    <twig:ui:Avatar>
        <twig:ui:Avatar:Image src="https://avatars.laravel.cloud/168544b7-8325-4ac9-a019-5316d1824b0e?vibe=forest" alt="Alex Doe" />
        <twig:ui:Avatar:Fallback>AD</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
    <twig:ui:Avatar:GroupCount>+3</twig:ui:Avatar:GroupCount>
</twig:ui:Avatar:Group>

Sizes

NL NL NL NL NL

<div class="flex flex-wrap items-center gap-2">
    <twig:ui:Avatar size="xs">
        <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
        <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
    <twig:ui:Avatar size="sm">
        <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
        <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
    <twig:ui:Avatar>
        <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
        <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
    <twig:ui:Avatar size="lg">
        <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
        <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
    <twig:ui:Avatar size="xl">
        <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
        <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
</div>

RTL

Set dir="rtl" on a wrapping element to render avatars for right-to-left languages.

NL AD

NL JL AD

+٣

<div dir="rtl" class="flex flex-wrap items-center gap-6">
    <twig:ui:Avatar>
        <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
        <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
    </twig:ui:Avatar>
    <twig:ui:Avatar>
        <twig:ui:Avatar:Image src="https://avatars.laravel.cloud/168544b7-8325-4ac9-a019-5316d1824b0e?vibe=forest" alt="Alex Doe" />
        <twig:ui:Avatar:Fallback>AD</twig:ui:Avatar:Fallback>
        <twig:ui:Avatar:Badge class="bg-green-500 dark:bg-green-600" />
    </twig:ui:Avatar>
    <twig:ui:Avatar:Group>
        <twig:ui:Avatar>
            <twig:ui:Avatar:Image src="https://github.com/nicolaslps.png" alt="@nicolaslps" />
            <twig:ui:Avatar:Fallback>NL</twig:ui:Avatar:Fallback>
        </twig:ui:Avatar>
        <twig:ui:Avatar>
            <twig:ui:Avatar:Image src="https://avatars.laravel.cloud/1a5e26e9-6894-40fd-b37f-75286143c505?vibe=ocean" alt="Jamie Lee" />
            <twig:ui:Avatar:Fallback>JL</twig:ui:Avatar:Fallback>
        </twig:ui:Avatar>
        <twig:ui:Avatar>
            <twig:ui:Avatar:Image src="https://avatars.laravel.cloud/168544b7-8325-4ac9-a019-5316d1824b0e?vibe=forest" alt="Alex Doe" />
            <twig:ui:Avatar:Fallback>AD</twig:ui:Avatar:Fallback>
        </twig:ui:Avatar>
        <twig:ui:Avatar:GroupCount>+٣</twig:ui:Avatar:GroupCount>
    </twig:ui:Avatar:Group>
</div>

API Reference

`<twig:ui:Avatar>`

Prop	Type	Description
`size`	`'xs'` \| `'sm'` \| `'default'` \| `'lg'` \| `'xl'`	The size of the avatar. Defaults to `default`

Block	Description
`content`	The avatar content, typically an `Avatar:Image` and an `Avatar:Fallback`

`<twig:ui:Avatar:Image>`

Renders the <img> element. Hidden until it successfully loads, revealing itself and hiding the sibling Avatar:Fallback.

Prop	Type	Description
`src`	`string`	The image URL
`alt`	`string`	The image alt text. Defaults to `''`

`<twig:ui:Avatar:Fallback>`

Block	Description
`content`	The fallback content, typically initials or an icon

`<twig:ui:Avatar:Badge>`

Prop	Type	Description
`position`	`'top-start'` \| `'top-end'` \| `'bottom-start'` \| `'bottom-end'`	The corner the badge is anchored to. Defaults to `bottom-end`

Block	Description
`content`	Optional badge content, typically an icon. Empty for a plain status dot

`<twig:ui:Avatar:Group>`

Block	Description
`content`	The grouped avatars, typically multiple `Avatar` components followed by an optional `Avatar:GroupCount`

`<twig:ui:Avatar:GroupCount>`

Block	Description
`content`	The count indicator, typically `+N` text or an icon