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'

export const Basic = () => (
  <Avatar.Root>
    <Avatar.Fallback>PA</Avatar.Fallback>
    <Avatar.Image src="https://i.pravatar.cc/300" alt="avatar" />
  </Avatar.Root>
)

import { Avatar } from '@ark-ui/solid/avatar'

export const Basic = () => (
  <Avatar.Root>
    <Avatar.Fallback>PA</Avatar.Fallback>
    <Avatar.Image src="https://i.pravatar.cc/300" alt="avatar" />
  </Avatar.Root>
)

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

<template>
  <Avatar.Root>
    <Avatar.Fallback>PA</Avatar.Fallback>
    <Avatar.Image src="https://i.pravatar.cc/3000" alt="avatar" />
  </Avatar.Root>
</template>

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

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

Handling Events

Use onStatusChange to listen for loading state changes.

import { Avatar } from '@ark-ui/react/avatar'

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

import { Avatar } from '@ark-ui/solid/avatar'

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

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

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

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

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

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

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

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

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

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

import { Avatar, useAvatar } from '@ark-ui/solid/avatar'

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

  return (
    <>
      <button onClick={() => avatar().setSrc('https://new-source.com')}>Change Source</button>

      <Avatar.RootProvider value={avatar}>
        <Avatar.Fallback>PA</Avatar.Fallback>
        <Avatar.Image src="https://i.pravatar.cc/300" alt="avatar" />
      </Avatar.RootProvider>
    </>
  )
}

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

const avatar = useAvatar()
</script>

<template>
  <button @click="avatar.setSrc('https://new-source.com')">Change Source</button>

  <Avatar.RootProvider :value="avatar">
    <Avatar.Fallback>PA</Avatar.Fallback>
    <Avatar.Image src="https://i.pravatar.cc/3000" alt="avatar" />
  </Avatar.RootProvider>
</template>

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

  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 value={avatar}>
  <Avatar.Fallback>PA</Avatar.Fallback>
  <Avatar.Image {src} alt="avatar" />
</Avatar.RootProvider>

If you're using the Avatar.RootProvider component, you don't need to use the Avatar.Root component.

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

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.