Avatar

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

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.

Examples

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

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" alt="avatar" />
  </Avatar.Root>
)

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" alt="avatar" />
  </Avatar.Root>
)

<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" alt="avatar" />
  </Avatar.Root>
</template>

<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" alt="avatar" />
</Avatar.Root>

Handling Events

Use onStatusChange to listen for loading state changes.

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

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

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

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

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

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

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

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

<Avatar.Root class={styles.Root} onStatusChange={handleStatusChange}>
  <Avatar.Fallback class={styles.Fallback}>PA</Avatar.Fallback>
  <Avatar.Image class={styles.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.

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

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

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

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

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

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

  return (
    <>
      <button onClick={() => avatar().setSrc('https://new-source.com')}>Change Source</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" alt="avatar" />
      </Avatar.RootProvider>
    </>
  )
}

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

const avatar = useAvatar()
</script>

<template>
  <button @click="avatar.setSrc('https://new-source.com')">Change Source</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/3000" alt="avatar" />
  </Avatar.RootProvider>
</template>

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

  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 class={styles.Root} value={avatar}>
  <Avatar.Fallback class={styles.Fallback}>PA</Avatar.Fallback>
  <Avatar.Image class={styles.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.

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 for more information.

API Reference

Props

Root

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

Fallback

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

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

Image

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

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

RootProvider

Prop	Default	Type
`value`		`UseAvatarReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Context

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

API

Property	Type
`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.