Avatar

Used to represent user profile picture or initials

import { Avatar } from "@/components/ui/avatar"

const Demo = () => {
  return <Avatar name="Segun Adebayo" src="https://bit.ly/sage-adebayo" />
}

Setup

If you don't already have the snippet, run the following command to add the avatar snippet

npx @chakra-ui/cli snippet add avatar

The snippet includes a closed component composition for the Avatar and AvatarGroup components.

Usage

import { Avatar, AvatarGroup } from "@/components/ui/avatar"

<AvatarGroup>
  <Avatar />
</AvatarGroup>

Examples

Sizes

Use the size prop to change the size of the avatar

import { HStack } from "@chakra-ui/react"
import { Avatar } from "@/components/ui/avatar"

const Demo = () => {
  return (
    <HStack gap="3">
      <Avatar size="xs" name="Sage" src="https://bit.ly/sage-adebayo" />
      <Avatar size="sm" name="Sage" src="https://bit.ly/sage-adebayo" />
      <Avatar size="md" name="Sage" src="https://bit.ly/sage-adebayo" />
      <Avatar size="lg" name="Sage" src="https://bit.ly/sage-adebayo" />
      <Avatar size="xl" name="Sage" src="https://bit.ly/sage-adebayo" />
      <Avatar size="2xl" name="Sage" src="https://bit.ly/sage-adebayo" />
    </HStack>
  )
}

Variants

Use the variant prop to change the variant of the avatar

import { HStack } from "@chakra-ui/react"
import { Avatar } from "@/components/ui/avatar"

const Demo = () => {
  return (
    <HStack gap="3">
      <Avatar variant="solid" name="Sage Adebayo" />
      <Avatar variant="outline" name="Sage Adebayo" />
      <Avatar variant="subtle" name="Sage Adebayo" />
    </HStack>
  )
}

Shape

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

import { HStack } from "@chakra-ui/react"
import { Avatar } from "@/components/ui/avatar"

const Demo = () => {
  return (
    <HStack gap="4">
      <Avatar
        name="Dan Abramov"
        src="https://bit.ly/dan-abramov"
        shape="square"
        size="lg"
      />
      <Avatar
        name="Sage Adebayo"
        src="https://bit.ly/sage-adebayo"
        shape="rounded"
        size="lg"
      />
      <Avatar
        name="Random User"
        src="https://images.unsplash.com/photo-1531746020798-e6953c6e8e04"
        shape="full"
        size="lg"
      />
    </HStack>
  )
}

Fallback

The initials of the name can be used as a fallback when the src prop is not provided or when the image fails to load.

import { HStack } from "@chakra-ui/react"
import { Avatar } from "@/components/ui/avatar"

const Demo = () => {
  return (
    <HStack>
      <Avatar name="Oshigaki Kisame" src="https://bit.ly/broken-link" />
      <Avatar
        name="Sasuke Uchiha"
        src="https://bit.ly/broken-link"
        colorPalette="teal"
      />
      <Avatar src="https://bit.ly/broken-link" colorPalette="red" />
    </HStack>
  )
}

Random Color

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

import { HStack } from "@chakra-ui/react"
import { Avatar } from "@/components/ui/avatar"

const colorPalette = ["red", "blue", "green", "yellow", "purple", "orange"]

const pickPalette = (name: string) => {
  const index = name.charCodeAt(0) % colorPalette.length
  return colorPalette[index]
}

const Demo = () => {
  return (
    <HStack>
      <Avatar name="Shane Nelson" colorPalette={pickPalette("Shane Nelson")} />
      <Avatar name="Brook Lesnar" colorPalette={pickPalette("Brook Lesnar")} />
      <Avatar name="John Lennon" colorPalette={pickPalette("John Lennon")} />
    </HStack>
  )
}

Ring

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

import { HStack, defineStyle } from "@chakra-ui/react"
import { Avatar } from "@/components/ui/avatar"

const ringCss = defineStyle({
  outlineWidth: "2px",
  outlineColor: "colorPalette.500",
  outlineOffset: "2px",
  outlineStyle: "solid",
})

const Demo = () => {
  return (
    <HStack gap="4">
      <Avatar
        name="Random"
        colorPalette="pink"
        src="https://randomuser.me/api/portraits/men/70.jpg"
        css={ringCss}
      />
      <Avatar
        name="Random"
        colorPalette="green"
        src="https://randomuser.me/api/portraits/men/54.jpg"
        css={ringCss}
      />
      <Avatar
        name="Random"
        colorPalette="blue"
        src="https://randomuser.me/api/portraits/men/42.jpg"
        css={ringCss}
      />
    </HStack>
  )
}

Group

Use the Group component to group multiple avatars together

import { Avatar, AvatarGroup } from "@/components/ui/avatar"

const Demo = () => {
  return (
    <AvatarGroup size="lg">
      <Avatar
        src="https://cdn.myanimelist.net/r/84x124/images/characters/9/131317.webp?s=d4b03c7291407bde303bc0758047f6bd"
        name="Uchiha Sasuke"
      />
      <Avatar
        src="https://cdn.myanimelist.net/r/84x124/images/characters/7/284129.webp?s=a8998bf668767de58b33740886ca571c"
        name="Baki Ani"
      />
      <Avatar
        src="https://cdn.myanimelist.net/r/84x124/images/characters/9/105421.webp?s=269ff1b2bb9abe3ac1bc443d3a76e863"
        name="Uchiha Chan"
      />
      <Avatar variant="solid" fallback="+3" />
    </AvatarGroup>
  )
}

Stacking

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

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

const Demo = () => {
  return (
    <Stack>
      <AvatarGroup size="lg" stacking="last-on-top">
        {items.map((item) => (
          <Avatar key={item.name} src={item.src} name={item.name} />
        ))}
        <Avatar fallback="+3" />
      </AvatarGroup>

      <AvatarGroup size="lg" stacking="first-on-top">
        {items.map((item) => (
          <Avatar key={item.name} src={item.src} name={item.name} />
        ))}
        <Avatar fallback="+3" />
      </AvatarGroup>

      <AvatarGroup size="lg" spaceX="1" borderless>
        {items.map((item) => (
          <Avatar key={item.name} src={item.src} name={item.name} />
        ))}
        <Avatar fallback="+3" />
      </AvatarGroup>
    </Stack>
  )
}

const items = [
  {
    src: "https://cdn.myanimelist.net/r/84x124/images/characters/9/131317.webp?s=d4b03c7291407bde303bc0758047f6bd",
    name: "Uchiha Sasuke",
  },
  {
    src: "https://cdn.myanimelist.net/r/84x124/images/characters/7/284129.webp?s=a8998bf668767de58b33740886ca571c",
    name: "Baki Ani",
  },
  {
    src: "https://cdn.myanimelist.net/r/84x124/images/characters/9/105421.webp?s=269ff1b2bb9abe3ac1bc443d3a76e863",
    name: "Uchiha Chan",
  },
]

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

import { HStack, Stack, Text } from "@chakra-ui/react"
import { Avatar } from "@/components/ui/avatar"

const Demo = () => {
  return (
    <Stack gap="8">
      {users.map((user) => (
        <HStack key={user.email} gap="4">
          <Avatar name={user.name} size="lg" src={user.avatar} />
          <Stack gap="0">
            <Text fontWeight="medium">{user.name}</Text>
            <Text color="fg.muted" textStyle="sm">
              {user.email}
            </Text>
          </Stack>
        </HStack>
      ))}
    </Stack>
  )
}

const users = [
  {
    id: "1",
    name: "John Mason",
    email: "john.mason@example.com",
    avatar: "https://i.pravatar.cc/300?u=iu",
  },
  {
    id: "2",
    name: "Melissa Jones",
    email: "melissa.jones@example.com",
    avatar: "https://i.pravatar.cc/300?u=po",
  },
]

Badge

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

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

const Demo = () => {
  return (
    <Avatar.Root colorPalette="green" variant="subtle">
      <Avatar.Fallback>DA</Avatar.Fallback>
      <Float placement="bottom-end" offsetX="1" offsetY="1">
        <Circle
          bg="green.500"
          size="8px"
          outline="0.2em solid"
          outlineColor="bg"
        />
      </Float>
    </Avatar.Root>
  )
}

Overflow

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

import { Group } from "@chakra-ui/react"
import { Avatar } from "@/components/ui/avatar"
import {
  MenuContent,
  MenuItem,
  MenuRoot,
  MenuTrigger,
} from "@/components/ui/menu"

const names = [
  "Naruto Uzumaki",
  "Sakura Haruno",
  "Kakashi Hatake",
  "Hinata Hyuga",
  "Shikamaru Nara",
]

const maxAvatars = 3

const Demo = () => {
  const { items, overflow } = partition(names, maxAvatars)
  return (
    <Group gap="0" spaceX="2">
      {items.map((item) => (
        <Avatar key={item} name={item} colorPalette={pickPalette(item)} />
      ))}
      {overflow.length > 0 && (
        <MenuRoot positioning={{ placement: "bottom" }}>
          <MenuTrigger rounded="full" focusRing="outside">
            <Avatar variant="outline" fallback={`+${overflow.length}`} />
          </MenuTrigger>
          <MenuContent>
            {overflow.map((item) => (
              <MenuItem value={item} key={item}>
                <Avatar
                  size="xs"
                  name={item}
                  colorPalette={pickPalette(item)}
                />
                {item}
              </MenuItem>
            ))}
          </MenuContent>
        </MenuRoot>
      )}
    </Group>
  )
}

const colorPalette = ["red", "blue", "green", "yellow", "purple", "orange"]

const pickPalette = (name: string) => {
  const index = name.charCodeAt(0) % colorPalette.length
  return colorPalette[index]
}

const partition = (arr: string[], max: number) => {
  const items = []
  const overflow = []
  for (const item of arr) {
    if (items.length < max) items.push(item)
    else overflow.push(item)
  }
  return { items, overflow }
}

Without Snippet

Here's an example of how to use the Avatar without the snippet.

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

const Demo = () => {
  return (
    <Avatar.Root>
      <Avatar.Image src="https://bit.ly/sage-adebayo" />
      <Avatar.Fallback>SA</Avatar.Fallback>
    </Avatar.Root>
  )
}

Props

Root

Prop	Default	Type
`colorPalette`	`'gray'`	`'gray' \| 'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'cyan' \| 'purple' \| 'pink' \| 'accent'` The color palette of the component
`size`	`'md'`	`'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
`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.
`borderless`		`'true' \| 'false'` The borderless of the component
`as`		`React.ElementType` The underlying element to render.
`unstyled`		`boolean` Whether to remove the component's style.

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.
`name`		`string`
`icon`		`React.ReactElement`

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.

Alert

Badge

Avatar

.css-vfo6uh{color:var(--chakra-colors-fg);-webkit-text-decoration:underline;text-decoration:underline;text-underline-offset:3px;text-decoration-thickness:2px;text-decoration-color:var(--chakra-colors-border-emphasized);font-weight:500;}Setup

Setup