Avatar

A person's or account's picture, falling back to their initials when there is no image or it fails to load.

Displayv0.1.0experimentalWCAG 2.2 AAView spec

import { Avatar } from "@rdloom/react";

export default function AvatarBasicExample() {
  return (
    <div className="flex items-center gap-3">
      <Avatar name="Ada Lovelace" />
      <Avatar name="Grace Hopper" shape="square" />
      <Avatar name="Linus" />
    </div>
  );
}

Installation

CLI

Manual

npm

pnpm

yarn

bun

npx rdloom add avatar

Copies the source into src/components/rdloom. Edit it freely: rdloom upgrade merges later versions into your changes.

Use another registry client

npx shadcn@latest add https://rdloom.vimalbhatt.com/r/avatar.json

Works, but without upgrade tracking.

Usage

import { Avatar } from "@rdloom/react";

<div className="flex items-center gap-3">
  <Avatar name="Ada Lovelace" />
  <Avatar name="Grace Hopper" shape="square" />
  <Avatar name="Linus" />
</div>

Sizes

import { Avatar } from "@rdloom/react";

export default function AvatarSizesExample() {
  return (
    <div className="flex items-end gap-3">
      <Avatar name="Ada Lovelace" size="xs" />
      <Avatar name="Ada Lovelace" size="sm" />
      <Avatar name="Ada Lovelace" size="md" />
      <Avatar name="Ada Lovelace" size="lg" />
    </div>
  );
}

Fallback

Image fails to load

Margaret Hamilton

import { Avatar } from "@rdloom/react";

// A missing or broken image falls back to the initials. When the name is already
// written next to the avatar, `decorative` keeps screen readers from saying it twice.
export default function AvatarFallbackExample() {
  return (
    <div className="flex flex-col gap-3 text-sm">
      <div className="flex items-center gap-2">
        <Avatar name="Katherine Johnson" src="data:image/png;base64,AAAA" />
        <span>Image fails to load</span>
      </div>
      <div className="flex items-center gap-2">
        <Avatar name="Margaret Hamilton" decorative />
        <span>Margaret Hamilton</span>
      </div>
    </div>
  );
}

API Reference

Defined by the spec. Components also accept the props of the React Aria component they wrap.

Prop	Type	Default
`name`required The person's name. It is the accessible name, and the source of the initials.	`string`	none
`src` Image URL. If it is missing or fails to load, the initials show instead.	`string`	none
`size` 24, 32, 40 or 56 px.	`"xs" \| "sm" \| "md" \| "lg"`	`"md"`
`shape` Circle for people, square for organisations.	`"circle" \| "square"`	`"circle"`
`decorative` Hides it from screen readers, for when the name is already written next to it.	`boolean`	`false`

Accessibility

Role img, WCAG 2.2 AA. Tested with axe and keyboard tests; screen reader checks are in the audit checklist.

Keyboard

Not interactive.

Screen readers announce

Announced as an image named after the person, e.g. "Ada Lovelace", unless decorative

What your code must do

It is an image with the person's name as its text alternative
With decorative set, it is hidden from assistive technology so a name next to it isn't read twice
Initials text meets 4.5:1 against the background

Guidelines

Use it when

Showing who wrote, owns or is assigned something
Account or user menus

Avoid it when

A logo or product image: use an img

Don't

Setting decorative when no name is written beside the avatar
An empty name

Design tokens

The semantic tokens this component uses. Change them once and every component follows; see Design tokens.

--rd-color-surface-subtle
--rd-color-text-default
--rd-color-border-default