Avatar

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

Examples Code Usage Migration guide Changelog

Default

When the image source is unavailable (for example, when there's a problem displaying the image due to an error), or the source is unspecified, the avatar component will display a default image.

When an avatar is not given any useful context via the name, presence, or status attributes like in this example, it will be hidden for assistive technologies as it does not convey any meaningful information.

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

const AvatarDefaultExample = (): React.JSX.Element => {
	return <Avatar />;
};

export default AvatarDefaultExample;

Accessibility

If an image is decorative – i.e. it doesn’t add any information to a page or the information in the image is already on the page as text – remove the name prop or provide an empty string so it’s ignored by assistive technology.

This reduces noise for people using assistive technology.

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

/**
 * Use `label=""` to mark an avatar as decorative (purely visual, no semantic meaning).
 * Screen readers will skip the avatar image when accompanied by visible text that already identifies the user.
 */
export default (): React.JSX.Element => (
	<Avatar
		src="https://pbs.twimg.com/profile_images/803832195970433027/aaoG6Skh_400x400.jpg"
		name="John Smith"
		label=""
		size="medium"
		testId="avatar"
	/>
);

Appearance

Circle

Use circle avatars to represent a person.

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

const AvatarCircleExample = (): React.JSX.Element => {
	return (
		<Avatar
			appearance="circle"
			src="https://pbs.twimg.com/profile_images/803832195970433027/aaoG6PJI_400x400.jpg"
			size="large"
			name="Scott Farquhar"
		/>
	);
};

export default AvatarCircleExample;

Hexagon

Use hexagon avatars to represent an agent entity, such as Rovodev or other AI-powered entities.

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

const AvatarHexagonExample = (): React.JSX.Element => (
	<Avatar name="Rovo" appearance="hexagon" size="large" presence="online" />
);

export default AvatarHexagonExample;

Square

Use square avatars to represent other entities, such as a project, repository or space.

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

import ExampleImg from '../../examples-util/nucleus.png';

const AvatarSquareExample = (): React.JSX.Element => {
	return <Avatar appearance="square" size="medium" src={ExampleImg} name="Nucleus" />;
};

export default AvatarSquareExample;

States

Disabled

Set isDisabled to disable an avatar that isn't usable. This sets the avatar image to 40% opacity using the opacity.disabled token.

Avoid using disabled UI. This can cause accessibility problems, because disabled UI doesn't give enough information to the user about what went wrong and how to proceed, and will not appear in the tab order.

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

const AvatarDisabledExample = (): React.JSX.Element => {
	return (
		<Avatar
			src="https://pbs.twimg.com/profile_images/803832195970433027/aaoG6PJI_400x400.jpg"
			name="Scott Farquhar"
			isDisabled
		/>
	);
};

export default AvatarDisabledExample;

Status

Indicates contextual information by showing a small icon on the avatar. Takes precedence over presence.

Approved

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

const AvatarStatusApprovedExample = (): React.JSX.Element => {
	return <Avatar name="John Smith" status="approved" />;
};

export default AvatarStatusApprovedExample;

Declined

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

const AvatarStatusDeclinedExample = (): React.JSX.Element => {
	return <Avatar name="John Smith" status="declined" />;
};

export default AvatarStatusDeclinedExample;

Locked

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

const AvatarStatusLockedExample = (): React.JSX.Element => {
	return <Avatar name="John Smith" status="locked" />;
};

export default AvatarStatusLockedExample;

Warning

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

const AvatarStatusWarningExample = (): React.JSX.Element => {
	return <Avatar name="John Smith" status="warning" />;
};

export default AvatarStatusWarningExample;

Presence

Indicates a user's online status by showing a small icon on the avatar.

Busy

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

const AvatarPresenceBusyExample = (): React.JSX.Element => {
	return <Avatar name="John Smith" presence="busy" />;
};

export default AvatarPresenceBusyExample;

Focus

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

const AvatarPresenceFocusExample = (): React.JSX.Element => {
	return <Avatar name="John Smith" presence="focus" />;
};

export default AvatarPresenceFocusExample;

Offline

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

const AvatarPresenceOfflineExample = (): React.JSX.Element => {
	return <Avatar name="John Smith" presence="offline" />;
};

export default AvatarPresenceOfflineExample;

Online

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

const AvatarPresenceOnlineExample = (): React.JSX.Element => {
	return <Avatar name="John Smith" presence="online" />;
};

export default AvatarPresenceOnlineExample;

Size

xxlarge

Use xxlarge avatars in places where larger avatars are needed. For example, the Atlassian People Directory.

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

import ExampleImg from '../../examples-util/nucleus.png';

const AvatarXXLargeExample = (): React.JSX.Element => {
	return (
		<div>
			<Avatar
				size="xxlarge"
				src="https://pbs.twimg.com/profile_images/803832195970433027/aaoG6PJI_400x400.jpg"
				name="Scott Farquhar"
			/>
			<Avatar size="xxlarge" appearance="square" src={ExampleImg} name="Nucleus" />
			<Avatar size="xxlarge" appearance="hexagon" src={ExampleImg} name="Nucleus" />
		</div>
	);
};

export default AvatarXXLargeExample;

xlarge

Use xlarge avatars where they're needed to display prominently on a page.

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

import ExampleImg from '../../examples-util/nucleus.png';

const AvatarXLargeExample = (): React.JSX.Element => {
	return (
		<div>
			<Avatar
				size="xlarge"
				src="https://pbs.twimg.com/profile_images/803832195970433027/aaoG6PJI_400x400.jpg"
				name="Scott Farquhar"
			/>
			<Avatar size="xlarge" appearance="square" src={ExampleImg} name="Nucleus" />
			<Avatar size="xlarge" appearance="hexagon" src={ExampleImg} name="Nucleus" />
		</div>
	);
};

export default AvatarXLargeExample;

large

Use large circle avatars to represent people for main page titles, like a user's account settings. Use large square avatars to represent main entity titles like Jira projects or Confluence spaces.

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

import ExampleImg from '../../examples-util/nucleus.png';

const AvatarLargeExample = (): React.JSX.Element => {
	return (
		<div>
			<Avatar
				size="large"
				src="https://pbs.twimg.com/profile_images/803832195970433027/aaoG6PJI_400x400.jpg"
				name="Scott Farquhar"
			/>
			<Avatar size="large" appearance="square" src={ExampleImg} name="Nucleus" />
			<Avatar size="large" appearance="hexagon" src={ExampleImg} name="Nucleus" />
		</div>
	);
};

export default AvatarLargeExample;

medium

Use medium circle avatars in activity streams or comments. Use medium square avatars in table views for project listings.

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

import ExampleImg from '../../examples-util/nucleus.png';

const AvatarMediumExample = (): React.JSX.Element => {
	return (
		<div>
			<Avatar
				size="medium"
				src="https://pbs.twimg.com/profile_images/803832195970433027/aaoG6PJI_400x400.jpg"
				name="Scott Farquhar"
			/>
			<Avatar size="medium" appearance="square" src={ExampleImg} name="Nucleus" />
			<Avatar size="medium" appearance="hexagon" src={ExampleImg} name="Nucleus" />
		</div>
	);
};

export default AvatarMediumExample;

small

Use small circle avatars in small areas like 40px text fields, and square avatars for use in things like dropdown menus.

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

import ExampleImg from '../../examples-util/nucleus.png';

const AvatarSmallExample = (): React.JSX.Element => {
	return (
		<div>
			<Avatar
				size="small"
				src="https://pbs.twimg.com/profile_images/803832195970433027/aaoG6PJI_400x400.jpg"
				name="Scott Farquhar"
			/>
			<Avatar size="small" appearance="square" src={ExampleImg} name="Nucleus" />
			<Avatar size="small" appearance="hexagon" src={ExampleImg} name="Nucleus" />
		</div>
	);
};

export default AvatarSmallExample;

xxsmall

Use xxsmall circle and square avatars for onscreen metadata such as in Jira work items or dropdown menus.

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';

import ExampleImg from '../../examples-util/nucleus.png';

const AvatarXSmallExample = (): React.JSX.Element => {
	return (
		<div>
			<Avatar
				size="xxsmall"
				src="https://pbs.twimg.com/profile_images/803832195970433027/aaoG6PJI_400x400.jpg"
				name="Scott Farquhar"
			/>
			<Avatar size="xxsmall" appearance="square" src={ExampleImg} name="Nucleus" />
			<Avatar size="xxsmall" appearance="hexagon" src={ExampleImg} name="Nucleus" />
		</div>
	);
};

export default AvatarXSmallExample;

xsmall (legacy)

In the current major, xsmall is retained as a legacy name for 16px avatars. Use xxsmall for new 16px usage. In a future major, xsmall will become the public 20px size; use UNSAFE_xsmall only as the temporary 20px migration value until then.

Motion in Early Access

The motion added into Avatar is in Early Access. The motion updates are currently behind the feature flag: platform-dst-motion-uplift.

You can display a tooltip with an avatar on focus or hover. The tooltip content should be set to the same value as the avatar label.

Don't use a tooltip with an avatar unless it is interactive. For more information, see the avatar component accessibilty guidelines.

Was this page helpful?

We use this feedback to improve our documentation.