Avatar

Displays a user profile image, initials, or a fallback icon. Unrecognized props (`id`, `tabIndex`, `title`, `data-*`, `aria-*`, event handlers, …) are forwarded to the root `<div>`.

Examples

Initials

AL

<Avatar name="Ada Lovelace" />

Shapes

circle

GH

SL

rounded

GH

SL

square

GH

SL

<VStack align="start" gap={6}>
  {shapes.map(shape => (
    <VStack align="start" gap={3} key={shape}>
      <Text weight="semibold">{shape}</Text>
      <HStack align="center" gap={4}>
        <Avatar
          name="Ada Lovelace"
          shape={shape}
          size="medium"
          src="https://i.pravatar.cc/256?img=47"
        />
        <Avatar name="Grace Hopper" shape={shape} size="medium" />
        <Avatar alt="Person placeholder" shape={shape} size="medium" />
        <Avatar
          alt="Silver organization logo"
          shape={shape}
          size="medium"
          src={organizationLogo}
        />
        <Avatar name="Silver Labs" shape={shape} size="medium" />
      </HStack>
    </VStack>
  ))}
</VStack>

Shapes With Status

AL

AL

AL

<HStack align="center" gap={6}>
  {shapes.map(shape => (
    <Avatar
      key={shape}
      name="Ada Lovelace"
      shape={shape}
      size="medium"
      status={<AvatarStatusDot label="Online" />}
    />
  ))}
</HStack>

Unicode Initials

😀R

🧑‍🚀S

Ñ

<div className={css({display: 'flex', alignItems: 'center', gap: 4})}>
  <Avatar name="😀 Rivera" size="medium" />
  <Avatar name="🧑‍🚀 Alice Smith" size="medium" />
  <Avatar name={'N\u0303oño'} size="medium" />
</div>

Image

<Avatar
  name="Ada Lovelace"
  alt="Ada Lovelace"
  src="https://i.pravatar.cc/256?img=47"
/>

Sizes

AL

AL

AL

AL

AL

<div style={{display: 'flex', alignItems: 'center', gap: 16}}>
  <Avatar name="Ada Lovelace" size="tiny" />
  <Avatar name="Ada Lovelace" size="xsmall" />
  <Avatar name="Ada Lovelace" size="small" />
  <Avatar name="Ada Lovelace" size="medium" />
  <Avatar name="Ada Lovelace" size="large" />
</div>

With Status

AL

GH

KJ

<div style={{display: 'flex', alignItems: 'center', gap: 16}}>
  <Avatar name="Ada Lovelace" status={<AvatarStatusDot label="Online" />} />
  <Avatar
    name="Grace Hopper"
    size="medium"
    status={<AvatarStatusDot icon={<Check />} label="Verified" />}
  />
  <Avatar
    name="Katherine Johnson"
    size="large"
    status={
      <AvatarStatusDot color="error" icon={<Check />} label="Unavailable" />
    }
  />
</div>

With Tooltip

AL

Ada Lovelace

Grace Hopper

KJ

Katherine Johnson

<div style={{display: 'flex', alignItems: 'center', gap: 16}}>
  <Avatar hasTooltip name="Ada Lovelace" size="medium" />
  <Avatar
    alt="Grace Hopper"
    hasTooltip
    name="Grace Hopper"
    size="medium"
    src="https://i.pravatar.cc/256?img=32"
  />
  <Avatar hasTooltip name="Katherine Johnson" size="medium" />
</div>

Fallback Src

<Avatar
  name="Ada Lovelace"
  src="https://broken.example.com/missing.png"
  fallbackSrc="https://i.pravatar.cc/256?img=47"
/>

Default Icon

<Avatar name={undefined} src={undefined} />

Numeric Sizes

AL

AL

AL

AL

AL

<div style={{display: 'flex', alignItems: 'center', gap: 16}}>
  <Avatar name="Ada Lovelace" size={16} />
  <Avatar name="Ada Lovelace" size={24} />
  <Avatar name="Ada Lovelace" size={48} />
  <Avatar name="Ada Lovelace" size={96} />
  <Avatar name="Ada Lovelace" size={144} />
</div>

Colors

R

O

Y

G

T

C

B

P

P

G

<div
  style={{
    display: 'flex',
    alignItems: 'center',
    gap: 16,
    flexWrap: 'wrap',
  }}>
  {colors.map(color => (
    <Avatar color={color} key={color} name={color} size="medium" />
  ))}
</div>

Auto Color From Name

AL

GH

KJ

AT

BL

DR

<div
  style={{
    display: 'flex',
    alignItems: 'center',
    gap: 16,
    flexWrap: 'wrap',
  }}>
  <Avatar name="Ada Lovelace" size="medium" />
  <Avatar name="Grace Hopper" size="medium" />
  <Avatar name="Katherine Johnson" size="medium" />
  <Avatar name="Alan Turing" size="medium" />
  <Avatar name="Barbara Liskov" size="medium" />
  <Avatar name="Dennis Ritchie" size="medium" />
</div>

Forwarded Props

AL

Unrecognized props (id, tabIndex, title, data-*, aria-*, event handlers) are forwarded to the root element — hover, focus, or inspect the avatar.

<div style={{display: 'flex', alignItems: 'center', gap: 16}}>
  <Avatar
    aria-describedby="ada-tooltip"
    data-analytics="avatar-ada"
    id="avatar-ada"
    name="Ada Lovelace"
    onMouseEnter={() => undefined}
    size="medium"
    tabIndex={0}
    title="Ada Lovelace"
  />
  <span id="ada-tooltip">
    Unrecognized props (<code>id</code>, <code>tabIndex</code>,{' '}
    <code>title</code>, <code>data-*</code>, <code>aria-*</code>, event
    handlers) are forwarded to the root element — hover, focus, or inspect
    the avatar.
  </span>
</div>

On Nav

Home

Settings

AL

Ada Lovelace

<div
  className={css({bg: 'bg.subtle'})}
  style={{width: 260, height: 320, padding: 12}}>
  <SideNav
    footer={{
      content: (
        <div style={{display: 'flex', alignItems: 'center', gap: 8}}>
          <Avatar name="Ada Lovelace" size="small" />
          <span>Ada Lovelace</span>
        </div>
      ),
    }}>
    <SideNavItem href="/home" icon={Home} label="Home" />
    <SideNavItem href="/settings" icon={Settings} label="Settings" />
  </SideNav>
</div>

API

Avatar

Displays a user profile image, initials, or a fallback icon. Unrecognized props (`id`, `tabIndex`, `title`, `data-*`, `aria-*`, event handlers, …) are forwarded to the root `<div>`.

Prop	Type	Default	Description
alt	string	—	Accessible text for the avatar image. Defaults to name, then "Avatar".
className	string	—	Additional CSS class names applied to the root element.
color	"red" | "orange" | "yellow" | "green" | "teal" | "cyan" | "blue" | "purple" | "pink" | "gray"	—	Surface color for the initials/icon fallback, which also drives the text color. When omitted, a hue is derived deterministically from name (fallbacks without initials use gray).
data-testid	string	—	Test ID applied to the root element.
fallbackSrc	string	—	Image URL to use if src fails to load.
hasTooltip	boolean	false	Shows name in a tooltip on hover and keyboard focus. Enabling it makes the avatar focusable, so the tooltip is reachable without a pointer. Ignored when there is no name.
name	string	—	User name used as fallback accessible text and initials.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the root element.
shape	"circle" | "rounded" | "square"	'circle'	Shape of the avatar. Rounded uses the theme's large corner radius.
size	"small" | "tiny" | "xsmall" | "medium" | "large" | 16 | 20 | 24 | 32 | 36 | 40 | 48 | 60 | 64 | 72 | 96 | 128 | 144 | 180	—	Avatar size. Named sizes map to the same pixel values as the XDS source. Default is small.
src	string	—	Primary image URL.
status	ReactNode	—	Corner content, usually an AvatarStatusDot.
style	CSSProperties	—	Inline styles applied to the root element.

AvatarStatusDot

Size-aware status indicator dot rendered in the corner of an Avatar. A thin wrapper around StatusDot that derives its size from the surrounding Avatar.

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the root element.
color	"error" | "info" | "success" | "warning" | "red" | "orange" | "yellow" | "green" | "teal" | "cyan" | "blue" | "purple" | "pink" | "gray" | "neutral"	'success'	Visual color. Accepts the same colors as Badge.
data-testid	string	—	Test ID applied to the root element.
icon	ReactNode	—	Optional icon rendered inside medium and large dots.
label*	string	—	Accessible label describing the status, such as "Online".
ref	Ref<HTMLDivElement>	—	Ref forwarded to the root element.
style	CSSProperties	—	Inline styles applied to the root element.