Summary

Avatars are used to add a human touch and instant clarity when understanding which user did what in the application. We also use avatars for projects, repositories, spaces and other container metaphors within Atlassian Apps.

Status

API status: general
Web resource key: com.atlassian.auiplugin:aui-avatar
AMD Module key: N/A
Experimental API: 5
General API: 5.1

Examples

The avatars have 7 size options: xsmall, small, medium, large, xlarge, xxlarge, xxxlrge

User Avatar User Avatar User Avatar User Avatar User Avatar User Avatar User Avatar Project Avatar Project Avatar Project Avatar Project Avatar Project Avatar Project Avatar Project Avatar

Usage

An avatar can be used as a web component (since 9.4.1) or an HTML composition.

Web Component

Avatar

If avatars are added as a web component, they are created with a specific tag <aui-avatar>. The avatars variations are created with specific attributes.

Variations

User avatars

Default example

Examples with attributes

Project avatars

Badged Avatar(s)

Avatars may have a single additional element overlaid in one of their four corners.

To add badge to avatar should be used the <aui-avatar-badged> component. It is an internal avatar component and it has to contain an SVG path or <img/>.

The position of badge is determined by the placement attribute

Avatars Group

The avatars can be a group in a stack. If the number of avatars is greater than 4, then a dropdown button with a number will appear at the end of the stack. This number shows how many avatars are hidden.

You can add an avatar group with <aui-avatar-group>.

You can declare the size of an avatar group with the "size" attribute (sets the size of all avatars in the stack).

HTML

If avatars are added like an HTML composition, they are created with <span> and specific class names. See below on how to use it.

Variations

User avatars

Project avatars

Avatars can be used for "container" objects — projects, spaces, repositories, etcetera — to give them a recognizable visual identity.

Badged Avatar(s)

Avatars may have a single additional element overlaid in one of their four corners.

Use badge to represent the type, permission, presence, or other contextually relevant information about the user or container.

The badge must also include a textual description of the information it represents so that its meaning can be conveyed and understood in non-visual contexts as well.

Options

Avatar component attributes

Attribute Description Possible Value Type Default
size Set the avatar size. xmsall, small, medium, large, xlarge, xxlarge, xxxlarge string medium
type Set avatar type. user, project string user

Attributes for custom avatar image

Attribute Description Type Default
src Set custom image for avatar string Default image, such as in the avatar example in the documentation above.
alt Set alternative text for image string
title Custom title for avatar image string

Badged avatar component attributes

Attribute Description Possible Value Type Default
placement Set avatar badged position top-start, top-end, bottom-start, bottom-end string bottom-end

Avatar group attribute

Attribute Description Possible Value Type Default
size Set the avatars group size (with all avatars in the group) xsmall, small, medium, large, xlarge, xxlarge, xxxlarge string medium

A11Y guidelines

Side note: whether you'd follow these guidelines or not, it's always advised to at least test your markup with a screen reader software.

Textual descriptions of avatars

An avatar must include a textual description of the concept it represents so that its meaning can be conveyed and understood in non-visual contexts as well.

  • In most cases, the avatar's <img> tag should include an alt attribute describing the image.
  • In cases where the avatar is logically grouped with text content that describes the concept (for example, in a page header), the avatar is effectively decorative. In such cases, you should provide an empty alt attribute description.
  • Web components automatically provide alt='' if no alt is passed.
Web Components
HTML

Avatar's badge status

Badged Avatar needs to have a text description of the status it symbolizes, ensuring that its purpose can be communicated and comprehended by screen readers. Add the aria-label attribute to the first tag of the component. This attribute should provide a descriptive text explaining the image and the meaning of the status.

Web Components

While using HTMl version of Avatar component you need to add:

  • role="img" to the first span tag
  • aria-label to the first span tag
  • provide empty alt attribute to the img tags inside the component.

HTML

Recommendation

Please use the Web Accessibility Initiative (WAI) patterns as a reference for implementing accessible components.