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" />

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
        icon={<Check />}
        label="Unavailable"
        variant="error"
      />
    }
  />
</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={
      <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.
name	string	—	User name used as fallback accessible text and initials.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the root element.
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.

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the root element.
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.
variant	"error" | "success" | "neutral"	—	Semantic dot color. Default is success.