Avatar

Represents a user or entity with a recognizable image or placeholder in UI elements.

HB
 <script lang="ts">  import { Avatar } from "bits-ui"; </script>   <Avatar.Root  delayMs={200}  class="data-[status=loaded]:border-foreground bg-muted text-muted-foreground h-12 w-12 rounded-full border text-[17px] font-medium uppercase data-[status=loading]:border-transparent" >  <div  class="flex h-full w-full items-center justify-center overflow-hidden rounded-full border-2 border-transparent"  >  <Avatar.Image src="/avatar-1.png" alt="@huntabyte" />  <Avatar.Fallback class="border-muted border">HB</Avatar.Fallback>  </div> </Avatar.Root>

Overview

The Avatar component provides a consistent way to display user or entity images throughout your application. It handles image loading states gracefully and offers fallback options when images fail to load, ensuring your UI remains resilient.

Features

  • Smart Image Loading: Automatically detects and handles image loading states
  • Fallback System: Displays alternatives when images are unavailable or slow to load
  • Compound Structure: Flexible primitives that can be composed and customized
  • Customizable: Choose to show the image immediately without a load check when you're certain the image will load.

Architecture

The Avatar component follows a compound component pattern with three key parts:

  • Avatar.Root: Container that manages the state of the image and its fallback
  • Avatar.Image: Displays user or entity image
  • Avatar.Fallback: Shows when the image is loading or fails to load

Quick Start

To get started with the Avatar component, you can use the Avatar.Root, Avatar.Image, and Avatar.Fallback primitives to create a basic avatar component:

 <script lang="ts">  import { Avatar } from "bits-ui"; </script>   <Avatar.Root>  <Avatar.Image  src="https://github.com/huntabyte.png"  alt="Huntabyte's avatar"  />  <Avatar.Fallback>HB</Avatar.Fallback> </Avatar.Root>

Reusable Components

You can create your own reusable Avatar component to maintain consistent styling and behavior throughout your application:

UserAvatar.svelte
 <script lang="ts">  import { Avatar, type WithoutChildrenOrChild } from "bits-ui";    let {  src,  alt,  fallback,  ref = $bindable(null),  imageRef = $bindable(null),  fallbackRef = $bindable(null),  ...restProps  }: WithoutChildrenOrChild<Avatar.RootProps> & {  src: string;  alt: string;  fallback: string;  imageRef?: HTMLImageElement | null;  fallbackRef?: HTMLElement | null;  } = $props(); </script>   <Avatar.Root {...restProps} bind:ref>  <Avatar.Image {src} {alt} bind:ref={imageRef} />  <Avatar.Fallback bind:ref={fallbackRef}>  {fallback}  </Avatar.Fallback> </Avatar.Root>

Then use it throughout your application:

+page.svelte
 <script lang="ts">  import UserAvatar from "$lib/components/UserAvatar.svelte";    const users = [  { handle: "huntabyte", initials: "HJ" },  { handle: "pavelstianko", initials: "PS" },  { handle: "adriangonz97", initials: "AG" },  ]; </script>   {#each users as user}  <UserAvatar  src="https://github.com/{user.handle}.png"  alt="{user.name}'s avatar"  fallback={user.initials}  /> {/each}

Customization

Skip Loading Check

When you're confident that an image will load (such as local assets), you can bypass the loading check:

 <script lang="ts">  import { Avatar } from "bits-ui";    // local asset that's guaranteed to be available  import localAvatar from "/avatar.png"; </script>   <Avatar.Root loadingStatus="loaded">  <Avatar.Image src={localAvatar} alt="User avatar" />  <Avatar.Fallback>HB</Avatar.Fallback> </Avatar.Root>

Examples

Clickable with Link Preview

This example demonstrates how to create a clickable avatar composed with a Link Preview:

API Reference

Avatar.Root

The root component used to set and manage the state of the avatar.

Property Details
loadingStatus
onLoadingStatusChange
delayMs
ref
children
child
Data Attribute Details
data-status
data-avatar-root

Avatar.Image

The avatar image displayed once it has loaded.

Property Details
ref
children
child
Data Attribute Details
data-status
data-avatar-image

Avatar.Fallback

The fallback displayed while the avatar image is loading or if it fails to load

Property Details
ref
children
child
Data Attribute Details
data-status
data-avatar-fallback
Previous Aspect Ratio Next Button