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
| 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. |
Demonstrates the avatar fallback chain: primary image, fallback image, initials, then default icon.
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.
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.
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.
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.