# Avatar Documentation

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

This is a documentation section that potentially contains examples, demos, and other useful information related to a specific part of Bits UI. When helping users with this documentation, you can ignore the classnames applied to the demos unless they are relevant to the user's issue.

```svelte
<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-muted-foreground 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>
```

## 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:

```svelte
<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

```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

```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`- 'loading' \| 'loaded' \| 'error'                             | 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`- (status: LoadingStatus) => void                          | 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`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined`                     | | Data Attribute                              | Value                                                                                                                                                                                       | Description                                                                                     |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-status` | `enum`- 'loading' \| 'loaded' \| 'error' | 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`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                              | Value                                                                                                                                                                                       | Description                                                                                     |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `data-status` | `enum`- 'loading' \| 'loaded' \| 'error' | 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`- type SnippetProps = { props: Record\<string, unknown>; }; | Use render delegation to render your own element. See [Child Snippet](/docs/child-snippet) docs for more information.`Default:  undefined` | | Data Attribute                              | Value                                                                                                                                                                                       | Description                                                                                         |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-status` | `enum`- 'loading' \| 'loaded' \| 'error' | The loading status of the image.                                             |
| `data-avatar-fallback`                             | `''`                                                                                                                                                                               | Present on the fallback element. |