# Avatar

URL: https://ark-ui.com/docs/react/components/avatar
LLM: https://ark-ui.com/llms.txt/components/avatar

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

---

---
id: avatar
title: Avatar
description: A graphical representation of the user, often used in profile sections.
---



## Anatomy



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

## Examples

### Basic

Display a user's profile image with a fallback.

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

### Events

Use `onStatusChange` to listen for loading state changes.

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

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

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

### AvatarStack

Stack the first 3 avatars. The `+N` overflow is a `Menu.Trigger` that lists everyone else.

```tsx
import { Avatar } from '@ark-ui/react/avatar'
import { Menu } from '@ark-ui/react/menu'
import { Portal } from '@ark-ui/react/portal'
import styles from 'styles/avatar.module.css'
import menuStyles from 'styles/menu.module.css'

const users = [
  { id: 'pa', name: 'Pauline Adebayo', initials: 'PA', src: 'https://i.pravatar.cc/300?u=a' },
  { id: 'mk', name: 'Marcus Kim', initials: 'MK', src: 'https://i.pravatar.cc/300?u=b' },
  { id: 'jr', name: 'Jordan Reed', initials: 'JR', src: 'https://i.pravatar.cc/300?u=c' },
  { id: 'sl', name: 'Sara Liu', initials: 'SL', src: 'https://i.pravatar.cc/300?u=d' },
  { id: 'tw', name: 'Taylor West', initials: 'TW', src: 'https://i.pravatar.cc/300?u=e' },
]

const max = 3
const visible = users.slice(0, max)
const hidden = users.slice(max)

export const AvatarStack = () => (
  <div className={styles.Stack}>
    {visible.map((user) => (
      <Avatar.Root key={user.id} className={styles.Root}>
        <Avatar.Fallback className={styles.Fallback}>{user.initials}</Avatar.Fallback>
        <Avatar.Image className={styles.Image} src={user.src} alt={user.name} />
      </Avatar.Root>
    ))}
    {hidden.length > 0 && (
      <Menu.Root>
        <Menu.Trigger
          render={
            <Avatar.Root className={styles.Root}>
              <Avatar.Fallback className={styles.Fallback}>+{hidden.length}</Avatar.Fallback>
            </Avatar.Root>
          }
        />
        <Portal>
          <Menu.Positioner>
            <Menu.Content className={menuStyles.Content}>
              {hidden.map((user) => (
                <Menu.Item key={user.id} className={menuStyles.Item} value={user.id}>
                  <Avatar.Root className={styles.MenuAvatar}>
                    <Avatar.Fallback className={styles.Fallback}>{user.initials}</Avatar.Fallback>
                    <Avatar.Image className={styles.Image} src={user.src} alt={user.name} />
                  </Avatar.Root>
                  {user.name}
                </Menu.Item>
              ))}
            </Menu.Content>
          </Menu.Positioner>
        </Portal>
      </Menu.Root>
    )}
  </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

### Root

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`ids`**
Type: `Partial<{ root: string; image: string; fallback: string }>`
Required: false
Default Value: `undefined`
Description: The ids of the elements in the avatar. Useful for composition.

**`onStatusChange`**
Type: `(details: StatusChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: Functional called when the image loading status changes.

### Fallback

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-avatar-fallback`**: <uid>
**`data-state`**: "hidden" | "visible"

### Image

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-avatar-image`**: <uid>
**`data-state`**: "visible" | "hidden"

### RootProvider

#### Props

**`value`**
Type: `UseAvatarReturn`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `status` | `LoadStatus` | The current image loading status. |
| `loaded` | `boolean` | Whether the image is loaded. |
| `setLoaded` | `VoidFunction` | Function to set loaded state. |
| `setError` | `VoidFunction` | Function to set error state. |