Avatar

Storybook Figma

An avatar is a visual representation of a user or object.

Preview

Usage

The Avatar component is designed to prioritize different sources for content display. It will sequentially check for the availability of an image source (image-src) or content through the icon slot. If both are not provided, the avatar will extract and display initials from the full name (full-name). The resulting initials are extracted using the following logic:

  • If the string contains two or more words, the result will be the first character of the first and last word capitalized. E.g.: full-name: "Jaqueline Nackos" will result in: JN.
  • If the string contains only one word, the result will be the first two characters capitalized. E.g: full-name: "Jaqueline" will result in: JA. full-name: "10" will result in: 10.
  • If full-name is not provided, the result will be an empty string.
Type Usage
Icon When no username can be associated with the Avatar.
DP
 Initials When the user's name is known.
user avatar
 Image When a custom image has been uploaded.
person avatar
3
 Group When reflecting more than 2 participants.

Variants and Examples

Icon

Initials

If color is not provided, the avatar will display a random color. This can be deterministic, see seeded. The default color '000' is not included in randomized colors and can only be set manually.

Image

If image-src is not provided, or if image fails to load, the avatar will fall back to the initials extracted from the full-name.

Sizes

Group

Adds a count badge and CSS mask to the avatar based on the number of digits (1, 2, or 3). Currently available only with the xs avatar size.

Presence

Positions the Presence component at each size and applies a CSS mask to the avatar.

Overlay

Clickable

If you need to create a clickable avatar you can set the clickable prop. This will make the avatar a clickable component, set some styling and will be navigable by keyboard. In order for the clickable avatar to be fully accessible, you need to either set full-name, image-alt or icon-aria-label attributes.

Seeded

You may use a seed to make the randomly generated color be the same every time for that seed. This is useful if you want users to always have the same color, just pass in their unique user ID as the seed.

Vue API

Slots

Name
Description
icon

Slot for avatar icon. It will display if no imageSrc is provided
overlayIcon

Slot for overlay icon.

Props

Name
Description
Default
avatarClass

Used to customize the avatar container

 Type: string|array|object
''
canvasClass

Set classes on the avatar canvas. Wrapper around the core avatar image.

 Type: string|array|object
''
clickable

Makes the avatar focusable and clickable, emits a click event when clicked.

 Type: boolean
false
color

Set the avatar background to a specific color. If undefined will randomize the color which can be deterministic if the seed prop is set.

 Type: string
undefined
fullName

Full name used to extract initials.

 Type: string
''
group

Determines whether to show a group avatar. Limit to 2 digits max, more than 99 will be rendered as “99+”. if the number is 1 or less it would just show the regular avatar as if group had not been set.

 Type: number
undefined
iconAriaLabel

Descriptive label for the icon. To avoid a11y issues, set this prop if clickable and iconName are set.

 Type: string
undefined
iconClass

Pass through classes. Used to customize the avatar icon

 Type: string|array|object
''
iconSize

Icon size to be displayed on the avatar

 Type: string
Values: 100200300400500600700800
 ''
id

Id of the avatar content wrapper element

 Type: string
function() { return getUniqueString(); }
imageAlt

Alt attribute of the image, required if imageSrc is provided. Can be set to '' (empty string) if the image is described in text nearby

 Type: string
undefined
imageSrc

Source of the image

 Type: string
''
overlayClass

Used to customize the avatar overlay

 Type: string|array|object
''
overlayText

The text that overlays the avatar

 Type: string
''
presence

Determines whether to show the presence indicator for Avatar - accepts PRESENCE_STATES values: 'busy', 'away', 'offline', or 'active'. By default, it's null and nothing is shown.

 Type: string
Values: nullbusyawayofflineactive
 AVATAR_PRESENCE_STATES.NONE
presenceProps

A set of props to be passed into the presence component.

 Type: object
{}
seed

Pass in a seed to get the random color generation based on that string. For example if you pass in a user ID as the string it will return the same randomly generated colors every time for that user.

 Type: string
undefined
size

The size of the avatar

 Type: string
Values: xssmmdlgxl
 'md'

Events

Name
Description
click

Avatar click event

 Type: PointerEvent | KeyboardEvent

Classes

Class
Applies to
Description

Accessibility

Initial avatars' background and font color combinations have been paired to ensure minimum contrast is met.

When it comes to voiceover, avatars accompanying a label should generally be considered decorative, is not focusable, nor is it read out. An example is a user's avatar next to their name.

Avatars unaccompanied by labels, especially those representing functionality or navigation, should be focusable and read out in voiceover. Please refer to WCAG references for your specific usage.

Avatar documentation last updated Thursday, June 11, 2026