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 like an HTML composition or a web component (since 9.4.1).

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
AخA
 
<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 recognisable 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>

Behaviour

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.
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-xxxlarge">
                <span class="aui-avatar-inner">
                    <img src="images/avatar-project.svg" alt="" role="presentation" />
                </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>

Badged content

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

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

The badged content 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
Person McRealface Online
 
<span class="aui-avatar aui-avatar-xxlarge">
    <span class="aui-avatar-inner">
        <img src="images/avatar-person.svg" alt="Person McRealface" />
    </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;
}

Web Component

Avatar

If avatars are added like 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
 
<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>

Behaviour

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

Avatar's badged

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

To add badged 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 badged is determined by the placement attribute

Demo code
Result
Busy Online
 
<aui-avatar size="small">
    <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>
    <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">
    <aui-avatar-badged placement="top-end">
        <img src="https://icon-library.com/images/avatar-icon-images/avatar-icon-images-4.jpg" />
    </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 badge 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>

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

Avatar badged 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