Build faster with Premium Chakra UI Components 💎

Learn more
Skip to Content
DocsEnterpriseBlogShowcase
Sponsor

Avatar

Used to represent user profile picture or initials

SourceStorybookRecipeArk
SA

Setup

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

chakra 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

S
S
S
S
S
S

Variants

Use the variant prop to change the variant of the avatar

SA
SA
SA

Shape

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

DA
SA
RU

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.

OK
SU

Random Color

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

SN
BL
JL

Ring

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

R
R
R

Group

Use the Group component to group multiple avatars together

US
BA
UC
+3

Stacking

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

US
BA
UC
+3
US
BA
UC
+3
US
BA
UC
+3

Persona

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

JM

John Mason

john.mason@example.com

MJ

Melissa Jones

melissa.jones@example.com

Badge

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

DA

Overflow

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

NU
SH
KH

Manual

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

SA

Props

Root

PropDefaultType
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

PropDefaultType
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

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Previous

Alert

Next

Badge