# 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

<Anatomy id="avatar" />

```tsx
<Avatar.Root>
  <Avatar.Fallback />
  <Avatar.Image />
</Avatar.Root>
```

## Examples

### Basic

Display a user's profile image with a fallback.

**Example: basic**

#### React

```tsx
import { Avatar } from '@ark-ui/react/avatar'
import styles from 'styles/avatar.module.css'

export const Basic = () => (
  <Avatar.Root className={styles.Root}>
    <Avatar.Fallback className={styles.Fallback}>PA</Avatar.Fallback>
    <Avatar.Image className={styles.Image} src="https://i.pravatar.cc/300?u=a" alt="avatar" />
  </Avatar.Root>
)

```

#### Solid

```tsx
import { Avatar } from '@ark-ui/solid/avatar'
import styles from 'styles/avatar.module.css'

export const Basic = () => (
  <Avatar.Root class={styles.Root}>
    <Avatar.Fallback class={styles.Fallback}>PA</Avatar.Fallback>
    <Avatar.Image class={styles.Image} src="https://i.pravatar.cc/300?u=a" alt="avatar" />
  </Avatar.Root>
)

```

#### Vue

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

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

```

#### Svelte

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

<Avatar.Root class={styles.Root}>
  <Avatar.Fallback class={styles.Fallback}>PA</Avatar.Fallback>
  <Avatar.Image class={styles.Image} src="https://i.pravatar.cc/300?u=a" alt="avatar" />
</Avatar.Root>

```

### Events

Use `onStatusChange` to listen for loading state changes.

**Example: events**

#### React

```tsx
import { Avatar } from '@ark-ui/react/avatar'
import { useState } from 'react'
import styles from 'styles/avatar.module.css'

export const Events = () => {
  const [status, setStatus] = useState('loading...')

  return (
    <div className="vstack">
      <output>Status: {status}</output>
      <Avatar.Root className={styles.Root} onStatusChange={(e) => setStatus(e.status)}>
        <Avatar.Fallback className={styles.Fallback}>PA</Avatar.Fallback>
        <Avatar.Image className={styles.Image} src="https://i.pravatar.cc/3000?u=a" alt="avatar" />
      </Avatar.Root>
    </div>
  )
}

```

#### Solid

```tsx
import { Avatar } from '@ark-ui/solid/avatar'
import { createSignal } from 'solid-js'
import styles from 'styles/avatar.module.css'

export const Events = () => {
  const [status, setStatus] = createSignal('loading...')

  return (
    <div class="vstack">
      <output>Status: {status()}</output>
      <Avatar.Root class={styles.Root} onStatusChange={(e) => setStatus(e.status)}>
        <Avatar.Fallback class={styles.Fallback}>PA</Avatar.Fallback>
        <Avatar.Image class={styles.Image} src="https://i.pravatar.cc/3000?u=a" alt="avatar" />
      </Avatar.Root>
    </div>
  )
}

```

#### Vue

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

const status = ref('loading...')
</script>

<template>
  <div class="vstack">
    <output>Status: {{ status }}</output>
    <Avatar.Root :class="styles.Root" @status-change="(e) => (status = e.status)">
      <Avatar.Fallback :class="styles.Fallback">PA</Avatar.Fallback>
      <Avatar.Image :class="styles.Image" src="https://i.pravatar.cc/3000?u=a" alt="avatar" />
    </Avatar.Root>
  </div>
</template>

```

#### Svelte

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

  let status = $state('loading...')
</script>

<div class="vstack">
  <output>Status: {status}</output>
  <Avatar.Root class={styles.Root} onStatusChange={(e) => (status = e.status)}>
    <Avatar.Fallback class={styles.Fallback}>PA</Avatar.Fallback>
    <Avatar.Image class={styles.Image} src="https://i.pravatar.cc/3000?u=a" alt="avatar" />
  </Avatar.Root>
</div>

```

### Root Provider

An alternative way to control the avatar is to use the `RootProvider` component and the `useAvatar` hook. This way you
can access the state and methods from outside the component.

**Example: root-provider**

#### React

```tsx
import { Avatar, useAvatar } from '@ark-ui/react/avatar'
import { useState } from 'react'
import button from 'styles/button.module.css'
import styles from 'styles/avatar.module.css'

export const RootProvider = () => {
  const [count, setCount] = useState(0)
  const avatar = useAvatar()

  return (
    <div className="vstack">
      <button className={button.Root} onClick={() => setCount(count + 1)}>
        Change Avatar
      </button>

      <Avatar.RootProvider className={styles.Root} value={avatar}>
        <Avatar.Fallback className={styles.Fallback}>PA</Avatar.Fallback>
        <Avatar.Image className={styles.Image} src={`https://i.pravatar.cc/300?u=${count}`} alt="avatar" />
      </Avatar.RootProvider>
    </div>
  )
}

```

#### Solid

```tsx
import { Avatar, useAvatar } from '@ark-ui/solid/avatar'
import { createSignal } from 'solid-js'
import button from 'styles/button.module.css'
import styles from 'styles/avatar.module.css'

export const RootProvider = () => {
  const [count, setCount] = createSignal(0)
  const avatar = useAvatar()

  return (
    <div class="vstack">
      <button class={button.Root} onClick={() => setCount(count() + 1)}>
        Change Avatar
      </button>

      <Avatar.RootProvider class={styles.Root} value={avatar}>
        <Avatar.Fallback class={styles.Fallback}>PA</Avatar.Fallback>
        <Avatar.Image class={styles.Image} src={`https://i.pravatar.cc/300?u=${count()}`} alt="avatar" />
      </Avatar.RootProvider>
    </div>
  )
}

```

#### Vue

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

const count = ref(0)
const avatar = useAvatar()
</script>

<template>
  <div class="vstack">
    <button :class="button.Root" @click="count++">Change Avatar</button>

    <Avatar.RootProvider :class="styles.Root" :value="avatar">
      <Avatar.Fallback :class="styles.Fallback">PA</Avatar.Fallback>
      <Avatar.Image :class="styles.Image" :src="`https://i.pravatar.cc/300?u=${count}`" alt="avatar" />
    </Avatar.RootProvider>
  </div>
</template>

```

#### Svelte

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

  const id = $props.id()
  const avatar = useAvatar({ id })

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

<div class="vstack">
  <button class={button.Root} onclick={() => counter++}>Change Avatar</button>

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

```

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

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