# 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

``` ## 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: ```svelte HB ``` ## Reusable Components You can create your own reusable Avatar component to maintain consistent styling and behavior throughout your application: UserAvatar.svelte ```svelte {fallback} ``` Then use it throughout your application: +page.svelte ```svelte {#each users as user} {/each} ``` ## Customization ### Skip Loading Check When you're confident that an image will load (such as local assets), you can bypass the loading check: ```svelte HB ``` ## Examples ### Clickable with Link Preview This example demonstrates how to create a clickable avatar composed with a [Link Preview](/docs/components/link-preview): ```svelte

``` ## 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\; }; | 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\; }; | 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\; }; | 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. |

@huntabyte