Avatar

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

llms.txt
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:

	<script lang="ts">
  import { Avatar, LinkPreview } from "bits-ui";
  import CalendarBlank from "phosphor-svelte/lib/CalendarBlank";
  import MapPin from "phosphor-svelte/lib/MapPin";
</script>
 
<LinkPreview.Root>
  <LinkPreview.Trigger
    href="https://x.com/huntabyte"
    target="_blank"
    rel="noreferrer noopener"
    class="rounded-xs underline-offset-4 hover:underline focus-visible:outline-2 focus-visible:outline-offset-8 focus-visible:outline-black"
  >
    <Avatar.Root
      class="data-[status=loaded]:border-foreground bg-muted text-muted-foreground h-12 w-12 rounded-full border border-transparent text-[17px] font-medium uppercase"
    >
      <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>
  </LinkPreview.Trigger>
  <LinkPreview.Content
    class="border-muted bg-background shadow-popover w-[331px] rounded-xl border p-[17px]"
    sideOffset={8}
  >
    <div class="flex space-x-4">
      <Avatar.Root
        class="data-[status=loaded]:border-foreground bg-muted text-muted-foreground h-12 w-12 rounded-full border border-transparent text-[17px] font-medium uppercase"
      >
        <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>
      <div class="space-y-1 text-sm">
        <h4 class="font-medium">@huntabyte</h4>
        <p>I do things on the internet.</p>
        <div
          class="text-muted-foreground flex items-center gap-[21px] pt-2 text-xs"
        >
          <div class="flex items-center text-xs">
            <MapPin class="mr-1 size-4" />
            <span> FL, USA </span>
          </div>
          <div class="flex items-center text-xs">
            <CalendarBlank class="mr-1 size-4" />
            <span> Joined May 2020</span>
          </div>
        </div>
      </div>
    </div>
  </LinkPreview.Content>
</LinkPreview.Root>

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