Avatar

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

Anatomy

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

Examples

Basic

Display a user's profile image with a fallback.

Events

Use onStatusChange to listen for loading state changes.

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.

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

Renders a <div> element.

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

Renders a <span> element.

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.

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

Image

Renders a <img> element.

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.

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

RootProvider

Renders a <div> element.

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

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.