XDS — Design System

Avatar@xds/core v0.0.13 · 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.

Sub-components

Avatar is a compound component with 2 sub-components.

XDSAvatar

Displays a user avatar with image, initials fallback, and optional status indicator.

Prop	Type	Description
src	string	Primary image source URL.
fallbackSrc	string	Fallback image when primary fails.
name	string	User name for initials and alt text.
alt	string	Alt text (falls back to name).
size	XDSAvatarSize (default: 'small')	Avatar size (named or numeric pixel value).
status	ReactNode	Corner content for status indicators.

XDSAvatarStatusDot

Size-aware status indicator dot that reads avatar size from context and scales proportionally.

Prop	Type	Description
variant	'positive' \| 'neutral' \| 'negative' (default: 'positive')	Semantic color variant of the dot.
label	string	Accessible label for screen readers.
icon	ReactNode	Icon centered inside the dot (hidden at tiny sizes).

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.

Prop

Type

Description

src

string

Primary image source URL.

fallbackSrc

string

Fallback image when primary fails.

name

string

User name for initials and alt text.

alt

string

Alt text (falls back to name).

size

XDSAvatarSize (default: 'small')

Avatar size (named or numeric pixel value).

status

ReactNode

Corner content for status indicators.

Prop

Type

Description

variant

'positive' | 'neutral' | 'negative' (default: 'positive')

Semantic color variant of the dot.

label

string

Accessible label for screen readers.

icon

ReactNode

Icon centered inside the dot (hidden at tiny sizes).