Provide a reliable fallback chain: image, then initials, then icon.
Avatar
Identity marker with image, initials fallback, and optional semantic palette.
- .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
Fallbacks
Group
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.
Do and don't
Keep initials short so the avatar stays legible at small sizes.
Write meaningful alt text when the image conveys user identity.
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.