Provide a reliable fallback chain: image, then initials, then icon.
Avatar
Identity marker with image, initials fallback, and optional semantic palette.
A
B
C
D
E
F
G
- .source-avatar Avatar root
- .source-avatar-image Image layer when source exists
- .source-avatar-initials Initial fallback content
- .source-avatar-icon Icon fallback content
- [data-source-palette] Semantic accent option
Sizes
xs · 20px
sm · 28px
md · 36px
lg · 48px
xl · 64px
Fallbacks
AB
Initials
Icon
?
Neutral
Group
A
B
C
D
+3
Design intent
Avatar gives a face to a person, team, or entity. Its job is quick visual recognition in contexts where full names take too much space. The fallback chain from photo to initials to icon means there is always something to show, which makes it safe to use before images load or when profiles are incomplete.
Fallback order
Avatar renders image first, then initials, then icon fallback.
Keep initials to one or two letters and always provide alt for meaningful profile photos.
Palette usage
Use palette to accent system-generated avatars (teams, bots, placeholders). Keep user photo avatars neutral. Semantic palettes carry status meaning; categorical palettes (blue, green, red, etc.) are for visual differentiation — for instance, assigning a distinct color to each team or workspace.
B
G
R
O
Y
P
Pu
T
Do and don't
Do
Keep initials short so the avatar stays legible at small sizes.
Write meaningful alt text when the image conveys user identity.
Don't
Do not leave broken image placeholders when src fails.
Avoid long text inside avatars. It breaks readability and layout rhythm.
Do not use palette accents as decoration for user photos without semantic meaning.
Designer checklist
- Every photo with meaningful identity context has a descriptive alt attribute.
- Initials are one or two characters maximum to stay legible at small sizes.
- Palette-colored avatars meet 3:1 contrast against the surrounding background.
- In AvatarGroup, overlap does not hide avatars that carry primary identity information.
Avatar props
PropTypeDefaultDescription
srcstringnullImage URL.
altstringnullAlternative text for image.
namestringnullUsed for initials fallback.
sizexs | sm | md | lg | xlmdAvatar size.
paletteneutral | accent | success | warning | danger | info | blue | green | red | orange | yellow | pink | purple | tealneutralFallback accent palette. Semantic values carry status meaning; categorical values differentiate entities by color.
Accessibility notes
ItemGuidance
img[alt]Provide user-readable alternative text for profile photos.
Fallback iconDecorative fallback icon stays hidden from assistive tech.