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

```ripple
import { Avatar } from 'ark-ripple/avatar';
import styles from 'styles/avatar.module.css';

export component 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>
}

```

### Events

Use `onStatusChange` to listen for loading state changes.

**Example: events**

```ripple
import { Avatar } from 'ark-ripple/avatar';
import { track } from 'ripple';
import styles from 'styles/avatar.module.css';

export component Events() {
  let status = track('loading...');

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

```ripple
import { Avatar } from 'ark-ripple/avatar';
import { useAvatar } from 'ark-ripple/avatar';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/avatar.module.css';

export component RootProvider() {
  let count = track(0);
  const avatar = useAvatar();

  <div class="vstack">
    <button
      class={button.Root}
      onClick={() => {
        @count = @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>
}

```

## API Reference

### Props

**Component API Reference**

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


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