Avatar
Flexible user and entity avatars with fallbacks, status indicators, shapes and interaction.
Avatar represents a person, team or entity using an image, initials, an icon or custom content.
Content and fallback
Use image with an accessible alt or name. If the image fails, Avatar falls back to initials, initials derived from name, children, or icon.
<Avatar image="/avatar.jpg" name="Alex Johnson" alt="Alex Johnson" />
<Avatar name="Alex Johnson" />
<Avatar initials="MK" />
<Avatar icon={<UserIcon />} />Size, shape and appearance
size is xs, sm, default, lg, xl or xxl. The showcase includes ten content and state examples for each of the four common sizes: xs, sm, default and lg. shape is circle, rounded or square. variant is soft (default), solid or outline.
<Avatar name="Small" size="sm" />
<Avatar name="Large" size="lg" shape="rounded" variant="solid" />
<Avatar name="Team" size="xl" shape="square" variant="outline" />The default dimensions are:
| Size | Dimensions | Typical use |
|---|---|---|
xs | 24 × 24px | Dense tables, compact metadata and inline mentions. |
sm | 32 × 32px | Lists, comments and compact navigation. |
default | 40 × 40px | Standard profile and team references. |
lg | 48 × 48px | Cards, headers and prominent identity blocks. |
xl | 64 × 64px | Profile headers and large identity displays. |
xxl | 96 × 96px | Extra-large profile photos and prominent identity displays. |
Each size supports the same content sources and states: an image, initials derived from name, explicit initials, an icon or custom children, status indicators, loading and disabled states, as well as all three shapes and visual variants.
<Avatar size="xs" image="/avatar.jpg" alt="Small profile photo" />
<Avatar size="sm" initials="MK" variant="solid" />
<Avatar size="default" name="Alex Johnson" status="online" />
<Avatar size="lg" icon={<UserIcon />} shape="rounded" variant="outline" />
<Avatar size="xxl" image="/profile-photo.jpg" alt="Large profile photo" />Extra extra large examples
The xxl size is 96 × 96px and supports the same content and state combinations as every other size:
<Avatar size="xxl" image="/profile-photo.jpg" alt="Large profile photo" />
<Avatar size="xxl" name="Alex Johnson" />
<Avatar size="xxl" initials="MK" variant="solid" />
<Avatar size="xxl" icon={<UserIcon />} variant="outline" />
<Avatar size="xxl" name="Online" status="online" />
<Avatar size="xxl" name="Rounded" shape="rounded" />
<Avatar size="xxl" name="Loading" loading />Use xxl for prominent profile headers, account pages, team identity blocks or other places where the avatar is the primary visual focus. It is approximately 1.5 times larger than xl.
Status and states
status accepts online, offline, busy or away. Override its accessible announcement with statusLabel. loading displays a loading state; disabled reduces emphasis and disables interaction.
Interaction
Providing onClick makes Avatar keyboard accessible with button semantics. Enter and Space activate it. Use aria-label when the name is not visible.
Interactive avatars use the same motion language as Button: they lift by 2px on hover and return to their original position when pressed. Set hoverScale to scale the whole avatar by 1.06 instead of lifting it. Set disableHover to disable both hover motion and the hover shadow. These effects are only applied when onClick makes the avatar interactive.
<Avatar name="Lift on hover" onClick={openProfile} />
<Avatar name="Scale on hover" hoverScale onClick={openProfile} />
<Avatar name="No hover effect" disableHover onClick={openProfile} />API Reference
| Prop | Values | Default | Description |
|---|---|---|---|
image | string | — | Image URL. |
alt | string | name | Image alternative text. |
name | string | — | Accessible name and automatic initials source. |
initials | string | derived | Explicit fallback content. |
children / icon | ReactNode | — | Custom fallback content. |
size | xs | sm | default | lg | xl | xxl | default | Avatar dimensions. xxl is 96×96px, approximately 1.5 times the xl size. |
shape | circle | rounded | square | circle | Corner treatment. |
variant | soft | solid | outline | soft | Fallback appearance. |
status | online | offline | busy | away | — | Status indicator. |
statusLabel | string | status | Accessible status text. |
loading, disabled | boolean | false | State flags. |
hoverScale | boolean | false | Scales an interactive avatar to 1.06 on hover instead of lifting it. |
disableHover | boolean | false | Disables hover motion and shadow for an interactive avatar. |
onClick | function | — | Makes the avatar interactive. |
aria-label | string | name or alt | Accessible name for the avatar. |
className | string | — | Additional class name applied to the root element. |
When image is present, it takes precedence over fallback content. If the image fails to load, the fallback order is initials, initials derived from name, children, then icon. An interactive avatar supports Enter and Space keyboard activation and exposes button semantics.