# Avatar

URL: https://ark-ui.com/docs/components/avatar
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/avatar.mdx

A graphical representation of the user, often used in profile sections.

---

<ComponentPreview id="Avatar" />

## Anatomy

To set up the avatar correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="avatar" />

## Examples

Learn how to use the `Avatar` component in your project. Let's take a look at the most basic example:

**Example: basic**

#### React

```tsx
import { Avatar } from '@ark-ui/react/avatar'

export const Basic = () => (
  <Avatar.Root>
    <Avatar.Fallback>PA</Avatar.Fallback>
    <Avatar.Image src="https://i.pravatar.cc/300" alt="avatar" />
  </Avatar.Root>
)

```

#### Solid

```tsx
import { Avatar } from '@ark-ui/solid/avatar'

export const Basic = () => (
  <Avatar.Root>
    <Avatar.Fallback>PA</Avatar.Fallback>
    <Avatar.Image src="https://i.pravatar.cc/300" alt="avatar" />
  </Avatar.Root>
)

```

#### Vue

```vue
<script setup lang="ts">
import { Avatar } from '@ark-ui/vue/avatar'
</script>

<template>
  <Avatar.Root>
    <Avatar.Fallback>PA</Avatar.Fallback>
    <Avatar.Image src="https://i.pravatar.cc/3000" alt="avatar" />
  </Avatar.Root>
</template>

```

#### Svelte

```svelte
<script lang="ts">
  import { Avatar } from '@ark-ui/svelte/avatar'
</script>

<Avatar.Root>
  <Avatar.Fallback>PA</Avatar.Fallback>
  <Avatar.Image src="https://i.pravatar.cc/3000?u=a" alt="avatar" />
</Avatar.Root>

```

### Handling Events

Use `onStatusChange` to listen for loading state changes.

**Example: events**

#### React

```tsx
import { Avatar } from '@ark-ui/react/avatar'

export const Events = () => {
  const handleStatusChange = (details: Avatar.StatusChangeDetails) => {
    console.log(details.status)
  }
  return (
    <Avatar.Root onStatusChange={handleStatusChange}>
      <Avatar.Fallback>PA</Avatar.Fallback>
      <Avatar.Image src="https://i.pravatar.cc/3000" alt="avatar" />
    </Avatar.Root>
  )
}

```

#### Solid

```tsx
import { Avatar } from '@ark-ui/solid/avatar'

export const Events = () => {
  const handleStatusChange = (details: Avatar.StatusChangeDetails) => {
    console.log(details.status)
  }

  return (
    <Avatar.Root onStatusChange={handleStatusChange}>
      <Avatar.Fallback>PA</Avatar.Fallback>
      <Avatar.Image src="https://i.pravatar.cc/3000" alt="avatar" />
    </Avatar.Root>
  )
}

```

#### Vue

```vue
<script setup lang="ts">
import { Avatar } from '@ark-ui/vue/avatar'
</script>

<template>
  <Avatar.Root @status-change="(e) => console.log(e.status)">
    <Avatar.Fallback>PA</Avatar.Fallback>
    <Avatar.Image src="https://i.pravatar.cc/3000" alt="avatar" />
  </Avatar.Root>
</template>

```

#### Svelte

```svelte
<script lang="ts">
  import { Avatar } from '@ark-ui/svelte/avatar'

  const handleStatusChange = (details: Avatar.StatusChangeDetails) => {
    console.log(details.status)
  }
</script>

<Avatar.Root onStatusChange={handleStatusChange}>
  <Avatar.Fallback>PA</Avatar.Fallback>
  <Avatar.Image src="https://i.pravatar.cc/3000" alt="avatar" />
</Avatar.Root>

```

### Root Provider

Use the `useAvatar` hook to create the avatar store and pass it to the `Avatar.RootProvider` component. This allows you
to have maximum control over the avatar programmatically.

**Example: root-provider**

#### React

```tsx
import { Avatar, useAvatar } from '@ark-ui/react/avatar'

export const RootProvider = () => {
  const avatar = useAvatar()

  return (
    <>
      <button onClick={() => avatar.setSrc('https://avatars.githubusercontent.com/u/6916170?v=4')}>
        Change Source
      </button>

      <Avatar.RootProvider value={avatar}>
        <Avatar.Fallback>PA</Avatar.Fallback>
        <Avatar.Image src="https://avatars.githubusercontent.com/u/1846056?v=4" alt="avatar" />
      </Avatar.RootProvider>
    </>
  )
}

```

#### Solid

```tsx
import { Avatar, useAvatar } from '@ark-ui/solid/avatar'

export const RootProvider = () => {
  const avatar = useAvatar()

  return (
    <>
      <button onClick={() => avatar().setSrc('https://new-source.com')}>Change Source</button>

      <Avatar.RootProvider value={avatar}>
        <Avatar.Fallback>PA</Avatar.Fallback>
        <Avatar.Image src="https://i.pravatar.cc/300" alt="avatar" />
      </Avatar.RootProvider>
    </>
  )
}

```

#### Vue

```vue
<script setup lang="ts">
import { Avatar, useAvatar } from '@ark-ui/vue/avatar'

const avatar = useAvatar()
</script>

<template>
  <button @click="avatar.setSrc('https://new-source.com')">Change Source</button>

  <Avatar.RootProvider :value="avatar">
    <Avatar.Fallback>PA</Avatar.Fallback>
    <Avatar.Image src="https://i.pravatar.cc/3000" alt="avatar" />
  </Avatar.RootProvider>
</template>

```

#### Svelte

```svelte
<script lang="ts">
  import { Avatar, useAvatar } from '@ark-ui/svelte/avatar'

  const id = $props.id()
  const avatar = useAvatar({
    id,
    onStatusChange: (status) => {
      console.log('status', status)
    },
  })

  let counter = $state(0)
  const src = $derived(`https://i.pravatar.cc/300?u=${counter}`)
</script>

<button onclick={() => counter++}>Change Avatar</button>

<Avatar.RootProvider value={avatar}>
  <Avatar.Fallback>PA</Avatar.Fallback>
  <Avatar.Image {src} alt="avatar" />
</Avatar.RootProvider>

```

> If you're using the `Avatar.RootProvider` component, you don't need to use the `Avatar.Root` component.

## Guides

### Next.js Image

Here's an example of how to use the `Image` component from `next/image`.

```tsx
import { Avatar, useAvatarContext } from '@ark-ui/react/avatar'
import { getImageProps, type ImageProps } from 'next/image'

const AvatarNextImage = (props: ImageProps) => {
  const avatar = useAvatarContext()

  const { hidden, ...arkImageProps } = avatar.getImageProps()
  const nextImage = getImageProps(props)

  return (
    <img
      {...arkImageProps}
      {...nextImage.props}
      style={{
        ...props.style,
        // use visibility instead
        visibility: hidden ? 'hidden' : 'visible',
      }}
    />
  )
}

const Demo = () => {
  return (
    <Avatar.Root>
      <Avatar.Fallback>JD</Avatar.Fallback>
      <AvatarNextImage src="..." alt="" width={80} height={80} />
    </Avatar.Root>
  )
}
```

> Refer to this [Github Discussion](https://github.com/chakra-ui/ark/discussions/3147) for more information.

## API Reference

### Props

**Component API Reference**

#### React

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ids` | `Partial<{ root: string; image: string; fallback: string }>` | No | The ids of the elements in the avatar. Useful for composition. |
| `onStatusChange` | `(details: StatusChangeDetails) => void` | No | Functional called when the image loading status changes. |


**Fallback Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Fallback Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | avatar |
| `[data-part]` | fallback |
| `[data-state]` | "hidden" | "visible" |


**Image Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Image Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | avatar |
| `[data-part]` | image |
| `[data-state]` | "visible" | "hidden" |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseAvatarReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Solid

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ids` | `Partial<{ root: string; image: string; fallback: string }>` | No | The ids of the elements in the avatar. Useful for composition. |
| `onStatusChange` | `(details: StatusChangeDetails) => void` | No | Functional called when the image loading status changes. |


**Fallback Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'span'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Fallback Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | avatar |
| `[data-part]` | fallback |
| `[data-state]` | "hidden" | "visible" |


**Image Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'img'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Image Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | avatar |
| `[data-part]` | image |
| `[data-state]` | "visible" | "hidden" |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseAvatarReturn` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Vue

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; image: string; fallback: string }>` | No | The ids of the elements in the avatar. Useful for composition. |


**Fallback Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Fallback Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | avatar |
| `[data-part]` | fallback |
| `[data-state]` | "hidden" | "visible" |


**Image Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Image Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | avatar |
| `[data-part]` | image |
| `[data-state]` | "visible" | "hidden" |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `AvatarApi<PropTypes>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


#### Svelte

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; image: string; fallback: string }>` | No | The ids of the elements in the avatar. Useful for composition. |
| `onStatusChange` | `(details: StatusChangeDetails) => void` | No | Functional called when the image loading status changes. |
| `ref` | `Element` | No |  |


**Fallback Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'span'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Fallback Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | avatar |
| `[data-part]` | fallback |
| `[data-state]` | "hidden" | "visible" |


**Image Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'img'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Image Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | avatar |
| `[data-part]` | image |
| `[data-state]` | "visible" | "hidden" |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseAvatarReturn` | Yes |  |
| `ref` | `Element` | No |  |


### Context

These are the properties available when using `Avatar.Context`, `useAvatarContext` hook or `useAvatar` hook.

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `loaded` | `boolean` | Whether the image is loaded. |
| `setSrc` | `(src: string) => void` | Function to set new src. |
| `setLoaded` | `VoidFunction` | Function to set loaded state. |
| `setError` | `VoidFunction` | Function to set error state. |