Avatar

Help

Use Avatar as the outer container for user avatars. It renders either an AvatarImage (when a photo is available) or an AvatarText (initials fallback). Common scenarios include user profiles, comment threads, chat interfaces, account menus, and team member lists.

Syntax

<Avatar alt="..." src="..." initials="..." />

Props

Examples

Team member list:

<Avatar src="/team/alice.jpg" alt="Alice Smith" initials="AS" />
<Avatar src="/team/bob.jpg" alt="Bob Jones" initials="BJ" />
<Avatar alt="Charlie Brown" initials="CB" />

Keyboard Interactions

• None -- this is a decorative/informational component, not interactive

ARIA

• role="img" -- on the outer container, conveying that the entire avatar is an image representation
• aria-label -- set from the alt prop, providing the accessible name for the avatar
• aria-hidden="true" -- on the inner initials <span>, preventing duplicate announcements since the outer element already has aria-label

When to Use

• Use to display a user's visual identity, such as a profile photo or initials fallback, in headers, comment threads, chat messages, or contact lists.
• Use when you need graceful fallback from an image to initials when the photo is unavailable or fails to load.
• Use with AvatarImage for a photo and AvatarText as a fallback when no image is available.
• Use in contexts where quick visual identification of people helps users navigate, such as team rosters or conversation threads.
• Use with the alt prop to provide an accessible name for the avatar via aria-label.

When Not to Use

• Do not use for decorative icons or illustrations -- use Icon instead.
• Do not use for organisation logos or non-person images -- use Image with appropriate alt text.
• Do not use when only one avatar is shown alongside extended profile information -- use a Person component instead.

Headless

This component provides role="img", aria-label, and image-to-initials fallback logic with zero visual styling. The consumer is responsible for all CSS including circular framing, sizing, background color for initials, font styling, border, and shadow effects.

Styles

The consumer provides all CSS styling. The component renders with a .avatar class for targeting. No default styles are included — this is a fully headless component.

Testing

• Verify the component renders a <div> element with class avatar
• Verify role="img"` -- on the outer container, conveying that the entire avatar is an image representation
• Verify aria-label -- set from the alt` prop, providing the accessible name for the avatar
• Verify aria-hidden="true" -- on the inner initials <span>, preventing duplicate announcements since the outer element already has aria-label
• Verify keyboard interactions work correctly
• Verify pass-through attributes are applied

Advice

• Designers: Maintain consistent avatar sizes throughout the application. Use a contrasting background color behind initials text to ensure legibility.
• Developers: Always provide the alt prop for accessibility. When using both src and initials, the component automatically falls back to initials if the image fails to load.

Implementation Notes

• Renders a <div> element with class avatar
• Spreads restProps onto the root element for consumer customization

Composition

Avatar follows a parent/child composition pattern:

• Avatar -- outer <span> container with role="img" and aria-label for the accessible name.
• AvatarImage -- <img> element displayed when a valid image source is available.
• AvatarText -- <span> element displayed as a fallback with initials or short text.

<Avatar src="/photo.jpg" alt="Jane Doe" initials="JD" />

Related components

• avatar-image — an avatar indicator inside image such as a user photo
• avatar-text — an avatar indicator inner text such as a user name
• avatar-group — a group of avatar components

References

• WAI-ARIA Img Role: https://www.w3.org/TR/wai-aria-1.2/#img