# Avatar

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

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

## 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-scope`**: avatar
**`data-part`**: fallback
**`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-scope`**: avatar
**`data-part`**: image
**`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 |
|----------|------|-------------|
| `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. |