Avatars

Ask a question Design guidelines

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

Demo code
Result
AخA
 
<aui-avatar></aui-avatar>

Examples with attributes

Demo code
Result
image-avatar
 
<aui-avatar size="small"></aui-avatar>
<aui-avatar size="xxlarge" type="user"></aui-avatar>
<aui-avatar size="large" type="user"
    src="https://icon-library.com/images/avatar-icon-images/avatar-icon-images-4.jpg" title="my-customer-avatar"
    alt="image-avatar">
</aui-avatar>

Project avatars

Demo code
Result
project-image
 
<aui-avatar type="project"></aui-avatar>
<aui-avatar type="project" size="small"></aui-avatar>
<aui-avatar type="project" size="xxlarge"></aui-avatar>
<aui-avatar type="project" size="large" src="images/places-21.png" alt="project-image"
    title="my-customer-project-image">
</aui-avatar>

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

Demo code
Result
Busy Online
 
<aui-avatar size="small" aria-label="User (busy)">
    <aui-avatar-badged>
        <svg height="100%" version="1.1" viewBox="0 0 8 8" fill="#FF5630" width="100%"
            xmlns="http://www.w3.org/2000/svg">
            <description>Busy</description>
            <circle cx="4" cy="4" r="4"></circle>
        </svg>
    </aui-avatar-badged>
</aui-avatar>
<aui-avatar aria-label="User (online)">
    <aui-avatar-badged placement="top-start">
        <svg height="100%" version="1.1" viewBox="0 0 8 8" fill="#36B37E" width="100%"
            xmlns="http://www.w3.org/2000/svg">
            <description>Online</description>
            <circle cx="4" cy="4" r="4"></circle>
        </svg>
    </aui-avatar-badged>
</aui-avatar>
<aui-avatar size="xlarge" type="project" aria-label="Project (unknown status)">
    <aui-avatar-badged placement="top-end">
        <img src="https://icon-library.com/images/avatar-icon-images/avatar-icon-images-4.jpg" alt="" />
    </aui-avatar-badged>
</aui-avatar>

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).

Demo code
Result
 
<aui-avatar-group size="medium">
    <aui-avatar></aui-avatar>
    <aui-avatar></aui-avatar>
    <aui-avatar></aui-avatar>
    <aui-avatar></aui-avatar>
    <aui-avatar></aui-avatar>
    <aui-avatar></aui-avatar>
    <aui-avatar></aui-avatar>
</aui-avatar-group>

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

Demo code
Result
Person McRealface
 
<span class="aui-avatar aui-avatar-xxlarge">
    <span class="aui-avatar-inner">
        <img src="images/avatar-person.svg" alt="Person McRealface" />
    </span>
</span>

Project avatars

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

Demo code
Result
My super awesome project
 
<span class="aui-avatar aui-avatar-project aui-avatar-xlarge">
    <span class="aui-avatar-inner">
        <img src="images/avatar-project.svg" alt="My super awesome project" />
    </span>
</span>

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.

Demo code
Result
Online
 
<span class="aui-avatar aui-avatar-xxlarge" role="img" aria-label="Person McRealface (Online)">
    <span class="aui-avatar-inner">
        <img src="images/avatar-person.svg" alt="" />
    </span>
    <span class="custom-presence-indicator">
        <svg height="100%" version="1.1" viewBox="0 0 8 8" width="100%" xmlns="http://www.w3.org/2000/svg">
            <description>Online</description>
            <circle cx="4" cy="4" r="4"></circle>
        </svg>
    </span>
</span>
 
.aui-avatar .custom-presence-indicator {
/* position the indicator. AUI Avatars are a relative container. */
position: absolute;
bottom: 0;
right: 0;
/* size the indicator appropriately. content should not appear outside the indicator. */
width: 16px;
height: 16px;
overflow: hidden;
/* style the indicator. */
color: #00875A;
border: 3px solid #fff;
border-radius: 100%;
fill: #00875A;
}

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
Demo code
Result

My super awesome project

The avatar is related to this heading. If I were using a screen reader here, it would be redundant to hear the name of the project read out twice. So, we prevent the image from being described.

 
<header class="aui-page-header">
    <div class="aui-page-header-inner">
        <div class="aui-page-header-image">
            <aui-avatar type="project" title="my-super-project"></aui-avatar>
        </div>
        <div class="aui-page-header-main">
            <h2>My super awesome project</h2>
            <p>
                The avatar is related to this heading. If I were using a screen reader here,
                it would be redundant to hear the name of the project read out twice. So,
                we prevent the image from being described.
            </p>
        </div>
    </div>
</header>
HTML
Demo code
Result

My super awesome project

The avatar is related to this heading. If I were using a screen reader here, it would be redundant to hear the name of the project read out twice. So, we prevent the image from being described.

 
<header class="aui-page-header">
    <div class="aui-page-header-inner">
        <div class="aui-page-header-image">
            <span class="aui-avatar aui-avatar-project aui-avatar-medium">
                <span class="aui-avatar-inner">
                    <img src="images/avatar-project.svg" alt="" />
                </span>
            </span>
        </div>
        <div class="aui-page-header-main">
            <h2>My super awesome project</h2>
            <p>
                The avatar is related to this heading. If I were using a screen reader here,
                it would be redundant to hear the name of the project read out twice. So,
                we prevent the image from being described.
            </p>
        </div>
    </div>
</header>

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
 
<aui-avatar size="large" aria-label="Person McRealface (Online)" type="project">
    <aui-avatar-badged placement="top-end">
        <svg height="100%" version="1.1" viewBox="0 0 8 8" width="100%" fill="#36B37E"
            xmlns="http://www.w3.org/2000/svg">
            <description>Online</description>
            <circle cx="4" cy="4" r="4"></circle>
        </svg>
    </aui-avatar-badged>
</aui-avatar>

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
 
<span class="aui-avatar aui-avatar-xxlarge" role="img" aria-label="Person McRealface (Online)">
    <span class="aui-avatar-inner">
        <img src="images/avatar-person.svg" alt="" />
    </span>
    <span class="custom-presence-indicator">
        <svg height="100%" version="1.1" viewBox="0 0 8 8" width="100%" xmlns="http://www.w3.org/2000/svg">
            <description>Online</description>
            <circle cx="4" cy="4" r="4"></circle>
        </svg>
    </span>
</span>

Recommendation

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