Avatar

Used to represent user profile picture or initials

AI TipWant to skip the docs? Use the MCP Server

Usage

import { Avatar, AvatarGroup } from "@chakra-ui/react"

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

info

If you prefer a closed component composition, check out the snippet below.

Examples

Sizes

Use the size prop to change the size of the avatar

Variants

Use the variant prop to change the variant of the avatar

Shape

Use the shape prop to change the shape of the avatar, from rounded to square

Colors

Use the colorPalette prop to change the color of the avatar

gray

red

green

blue

teal

pink

purple

cyan

orange

yellow

Fallback

Render Avatar.Icon as the fallback when the name is not provided or when the image fails to load.

Random Color

Combine the colorPalette prop with some custom logic to dynamically change the color of the avatar

Ring

Use the outline* props to add a ring around the avatar

Group

Use the Group component to group multiple avatars together

Stacking

When using the AvatarGroup component, you can use the stacking prop to change the stacking order of the avatars

Persona

Here's an example of how to use the Avatar component to display a user persona.

John Mason

john.mason@example.com

Melissa Jones

melissa.jones@example.com

Badge

Show a badge on the right corner of the avatar by composing the Float and Circle components

Overflow

Here's an example of how to handle an overflow of avatars by composing the Menu and Avatar components.

Next.js

Here's an example of how to compose the avatar with Next.js Image.

import { getImageProps } from "next/image"

function Demo() {
  const imageProps = getImageProps({
    src: "/image.png",
  })
  return (
    <Avatar.Root>
      <Avatar.Fallback name="Segun Adebayo" />
      <Avatar.Image {...imageProps} />
    </Avatar.Root>
  )
}

Store

An alternative way to access the avatar state and methods is to use the RootProvider component and the useAvatar store hook.

not loaded

Closed Component

Here's how to setup the Avatar for a closed component composition.

import {
  Avatar as ChakraAvatar,
  AvatarGroup as ChakraAvatarGroup,
} from "@chakra-ui/react"
import * as React from "react"

type ImageProps = React.ImgHTMLAttributes<HTMLImageElement>

export interface AvatarProps extends ChakraAvatar.RootProps {
  name?: string
  src?: string
  srcSet?: string
  loading?: ImageProps["loading"]
  icon?: React.ReactElement
  fallback?: React.ReactNode
}

export const Avatar = React.forwardRef<HTMLDivElement, AvatarProps>(
  function Avatar(props, ref) {
    const { name, src, srcSet, loading, icon, fallback, children, ...rest } =
      props
    return (
      <ChakraAvatar.Root ref={ref} {...rest}>
        <ChakraAvatar.Fallback name={name}>
          {fallback || icon}
        </ChakraAvatar.Fallback>
        <ChakraAvatar.Image src={src} srcSet={srcSet} loading={loading} />
        {children}
      </ChakraAvatar.Root>
    )
  },
)

export const AvatarGroup = ChakraAvatarGroup

If you want to automatically add the closed component to your project, run the command:

npx @chakra-ui/cli snippet add avatar

Props

Root

Prop	Default	Type
`colorPalette`	`gray`	`'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink'` The color palette of the component
`size`	`md`	`'full' \| '2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` The size of the component
`variant`	`subtle`	`'solid' \| 'subtle' \| 'outline'` The variant of the component
`shape`	`full`	`'square' \| 'rounded' \| 'full'` The shape of the component
`as`		`React.ElementType` The underlying element to render.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`unstyled`		`boolean` Whether to remove the component's style.
`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.
`borderless`		`'true' \| 'false'` The borderless of the component

Fallback

Prop	Default	Type
`name`		`string \| undefined` The name to derive the initials from. If not provided, the fallback will display a generic icon.
`as`		`React.ElementType` The underlying element to render.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Image

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