Avatar

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

HB
	<script lang="ts">
  import { Avatar } from "bits-ui";
 
  let loadingStatus = $state<Avatar.RootProps["loadingStatus"]>("loading");
</script>
 
<Avatar.Root
  bind:loadingStatus
  class="h-12 w-12 rounded-full border {loadingStatus === 'loaded'
    ? 'border-foreground'
    : 'border-transparent'} bg-muted text-[17px] font-medium uppercase text-muted-foreground"
>
  <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 border-muted">HB</Avatar.Fallback>
  </div>
</Avatar.Root>

Overview

The Avatar component is designed to represent a user or entity within your application's user interface. It provides a flexible and accessible way to display profile pictures or placeholder images.

Key Features

  • Compound Component Structure: Offers a set of sub-components that work together to create a fully-featured avatar.
  • Fallback Mechanism: Provides a fallback when the primary image is unavailable or loading.
  • Customizable: Each sub-component can be styled and configured independently to match your design system.

Architecture

The Avatar component is composed of several sub-components, each with a specific role:

  • Root: The main container component that manages the state of the avatar.
  • Image: The primary image element that displays the user's profile picture or a representative image.
  • Fallback: The fallback element that displays alternative content when the primary image is unavailable or loading.

Structure

Here's an overview of how the Avatar component is structured in code:

	<script lang="ts">
	import { Avatar } from "bits-ui";
</script>
 
<Avatar.Root>
	<Avatar.Image />
	<Avatar.Fallback />
</Avatar.Root>

Reusable Components

You can create your own reusable components that combine the Avatar primitives and simplify the usage throughout your application. In the following example, we're creating a reusable MyAvatar component that takes in a src and fallback prop and renders an Avatar.Root component with an Avatar.Image and Avatar.Fallback component.

MyAvatar.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>

You could then use the MyAvatar component in your application like so:

+page.svelte
	<script lang="ts">
	import MyAvatar from "$lib/components/MyAvatar.svelte";
</script>
 
<MyAvatar src="https://github.com/huntabyte.png" alt="huntabyte" fallback="HJ" />

API Reference

Avatar.Root

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

Property Type Description
loadingStatus $bindable
enum

The loading status of the avatars source image. You can bind a variable to track the status outside of the component and use it to show a loading indicator or error message.

Default: undefined
onLoadingStatusChange
function

A callback function called when the loading status of the image changes.

Default: undefined
delayMs
number

How long to wait before showing the image after it has loaded. This can be useful to prevent a harsh flickering effect when the image loads quickly.

Default: 0
ref $bindable
HTMLDivElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-status
enum

The loading status of the image.

data-avatar-root
''

Present on the root element.

Avatar.Image

The avatar image displayed once it has loaded.

Property Type Description
ref $bindable
HTMLImageElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-status
enum

The loading status of the image.

data-avatar-image
''

Present on the root element.

Avatar.Fallback

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

Property Type Description
ref $bindable
HTMLSpanElement

The underlying DOM element being rendered. You can bind to this to get a reference to the element.

Default: undefined
children
Snippet

The children content to render.

Default: undefined
child
Snippet

Use render delegation to render your own element. See delegation docs for more information.

Default: undefined
Data Attribute Value Description
data-status
enum

The loading status of the image.

data-avatar-fallback
''

Present on the fallback element.