XDS — Design System

Avatar@xds/core v0.0.14 · XDSAvatar

Usage

Avatar represents a person or team with a profile photo, initials, or a default icon. Use it in comment headers, contact lists, chat messages, user cards, and anywhere you need to identify someone visually.

ts
import {XDSAvatar} from '@xds/core/Avatar'

Best practices

Guidance	Practices
Do	Always pass a name so the avatar can show initials if the photo fails to load, and so screen readers can announce who it represents.
Do	Pick a size that matches the context — tiny or xsmall for inline mentions, small or medium for lists and cards, large for profile headers.
Do	Add a status dot when knowing someone's availability matters, like in chat or team views.
Don't	Use Avatar for logos, product images, or anything that isn't a person or team — use an image or icon instead.
Don't	Force a square or custom shape — avatars are always circular to stay consistent across the system.

Examples

Common configurations, variations, and states.

Avatar — Fallback Chain

Demonstrates the avatar fallback chain: primary image, fallback image, initials, then default icon.

Avatar — Group

Overlap multiple avatars in a row to represent a group of people. Use for team lists, PR reviewers, or participant counts where you want to show faces without taking up much space.

Avatar — Initials

Show initials instead of a photo. The avatar extracts the first and last initials from the name automatically. Use when you only have a user name, like in anonymous accounts or new user onboarding.

Avatar — User Card

Place an avatar next to a name and role to create a user card row. Use for comment headers, contact lists, profile sections, or anywhere you need to identify a person at a glance.

Avatar — Photo

Show a profile photo at different sizes. Use when you have a user photo URL. If the image fails to load, initials are shown instead.

Avatar — Status Dot

Add a status dot to an avatar to show whether someone is online, away, or busy. Use in chat, messaging, or any UI where knowing availability matters.

Usage

import {XDSAvatar} from '@xds/core/Avatar'

Best practices

Guidance	Practices
Do	Always pass a name so the avatar can show initials if the photo fails to load, and so screen readers can announce who it represents.
Do	Pick a size that matches the context — tiny or xsmall for inline mentions, small or medium for lists and cards, large for profile headers.
Do	Add a status dot when knowing someone's availability matters, like in chat or team views.
Don't	Use Avatar for logos, product images, or anything that isn't a person or team — use an image or icon instead.
Don't	Force a square or custom shape — avatars are always circular to stay consistent across the system.