Report an issue

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>

Structure

	<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,
		fallback,
		...restProps
	}: WithoutChildrenOrChild<Avatar.RootProps> & {
		src: string;
		fallback: string;
	} = $props();
</script>
 
<Avatar.Root {...restProps}>
	<Avatar.Image {src} />
	<Avatar.Fallback>
		{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" fallback="HJ" />

API Reference

Avatar.Root

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

Property Type Description
loadingStatus bindable prop
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 prop
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 prop
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 prop
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.