Avatar
Avatars represent a person or entity. They come in three types — icon, initials, and image — and scale across six sizes. Use outlined or filled style to match the surrounding surface. Keep the type and style consistent within a group of avatars.
Icon · Outlined
Icon · Filled
Initials · Outlined
Initials · Filled
Image
preview
props
| Prop | Type | Default | Description |
|---|---|---|---|
type | 'icon' | 'initials' | 'image' | 'icon' | Controls the avatar content. Keep consistent across a group. |
size | 'xs' | 'small' | 'medium' | 'large' | 'xlarge' | '2xlarge' | 'medium' | Controls the overall diameter and internal proportions. |
avatarStyle | 'outlined' | 'filled' | 'outlined' | Visual treatment for icon and initials types. Has no effect on image. |
initials | string | — | Required when type is 'initials'. xs and small sizes show only the first character. |
src | string | — | Image URL. Required when type is 'image'. |
alt | string | '' | Alt text for image type. Empty string hides it from screen readers. |
color | string | — | Custom background colour for icon and initials. Replaces the default sand-2 fill. Pass the same value across a group for visual consistency. |
status | 'positive' | 'warning' | 'negative' | — | Optional status badge shown at the bottom-right of the avatar. Scales proportionally with all sizes. |
usage
Avatars are building blocks used inside other components like Avatar List Item. When displaying a group of avatars, keep the type, style, and colour consistent. Use the color prop to align with the surrounding intent.
When to use
- To represent a person, user, or entity alongside their name
- Inside Avatar List Item for activity feeds, participant lists, or onboarding steps
- In profile headers or summary cards at larger sizes (xlarge or 2xlarge)
Do not use
- Mix types or styles within the same group — all icon, all initials, or all image
- Mix fill colours across avatars in the same list
- Use the image type when photos aren’t reliably available for all items — fall back to initials or icon instead
sizes
styles
Outlined uses a subtle border and transparent background — best on white or light surfaces. Filled uses a solid background — use the color prop to match an intent colour and keep it consistent across a list. Never mix styles within the same group.
color token to match the surrounding intent.types
Choose the type that best reflects the data available. Prefer image when photos are reliably available, initials when names are known, and icon as the generic fallback. Never mix types in the same list.
status
Status badges communicate the current state of a person or entity. They scale proportionally across all avatar sizes and work with every type — icon, initials, and image. Always use a status that matches the actual sentiment; never use positive for a warning or error state.
Scales across all sizes