Avatar

v1.0.0 | View in Storybook

​

When to use

• Representing a user profile in collaboration features such as messaging, sharing, or comments.
• Providing a visual cue for accounts, teams, or organizations in collaborative interfaces.
• Signaling concepts or features such as an agent avatar.

​

When to use something else

• Decorative visuals for onboarding or Empty states: Use an illustration asset or icon instead of an Avatar.

​

Dos and don’ts

• Do size Avatars based on the context they are used in, i.e. use a Small Avatar when paired next to a Small Button.
• Do randomize colors when using the icon or initial icon types.
• Do mix image types with icon or initial types as needed.
• Don’t rely only on Avatars when a name is more useful for the context.

​

Behavior

• When space limits, use an overflow avatar with a dropdown Menu to indicate there are more users hidden.
• Avatars can be view-only or interactive, depending on the context.
• Avatars can display badge dots to indicate status or online presence.

​

Often used with

Badge (status dot), Tooltip (name or details), Menu for “+N” overflow stacks in collaborator lists.

​

Accessibility

• Image alt text: Provide descriptive alt text (e.g., alt="Sarah Connor") when the avatar stands alone. Use alt="" and aria-hidden="true" if accompanied by visible adjacent text labels.
• Fallback accessibility: Render plain text fallback initials inside the DOM with verified 4.5:1 contrast against the background container when images fail to load.

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

With icon

Use an Avatar with an icon when representing a non-person entity such as a team, service, or concept—for example, an AI agent or application.

​

With image

Use an Avatar with a profile image when a user’s photo is available to help collaborators quickly recognize individuals in lists, comments, or assignment UI.

​

All colorways

Choose an Avatar colorway to differentiate users or entities when no image is available; assign colors randomly but keep them consistent in the same session.

​

All sizes

Select an Avatar size based on context—smaller in dense lists and tables, larger in profile headers or detail views—to maintain visual hierarchy and legibility.

​

Avatar group spacing

Use Avatar group spacing to display multiple collaborators with consistent overlap and alignment, making it clear how many people are involved without consuming excessive horizontal space.

​

Overflow avatar with menu

Use an overflow Avatar with a menu when more collaborators exist than can be displayed inline; the overflow control reveals the full list on interaction.

​

Click interaction

Make an Avatar clickable when selecting or viewing a user profile is a primary action—for example, opening a collaborator’s details from a comment thread or clicking to follow a collaborator in a canvas environment.