Avatar - Web

For development, import Avatar from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Avatar consists of three primary elements that work together to visually represent an entity.

Avatar body
Status indicator (Optional)
Avatar Group

Options

The Avatar supports multiple content types, sizes, and grouping configurations to accommodate various representation scenarios.

Image

Initials

When an image is not used, the avatar displays initials derived from the name, calculated based on specific rules. When two or more words are used, the first letter of the first two words is used. When only one word is provided in the name, the first two letters are used. On ‘small’ Avatars, only the first letter is used regardless of what name is used.

Custom background colors

Avatars provide one color by default. They accept any color or Token value. Text color auto-calculates to achieve the highest available contrast. Use a Token value that supports theming.

Sizes

Type	Dimensions
Small	24px / 1.5rem
Medium	32px / 2rem
Large	48px / 3rem

Status

Avatars can also convey an online or offline status.

Grouping

Avatars can be grouped together in a condensed form. The specific spacing depends on the size of individual Avatars. Grouping also allows for a max count of Avatars, where a +X will be displayed in place of additional Avatars. This cutoff is configurable to any number.

Status in groups

Usage Guidelines

Standard	Requirement
DoReferencing a person or entity	Avatars are appropriate when referencing a person. They also represent other entities such as businesses. Follow local standards for business entity representation.
Don’tDisplaying icons or emojis	Avatars should be avoided to display icons or emojis, and an element such as a Button may be more appropriate.
Don’tIsolated shape changes	Shape is consistent when representing a category of entities. Deviating from this confuses users; see Don’t make isolated changes to an Avatar’s shape.
DoSeveral people together (Avatar Group)	Multiple Avatars represent a set of people or entities and display in a condensed, overlapping form.
DoLimited space (Avatar Group)	A set is too large to show in full; set a max count so a +X replaces the Avatars beyond it.
Don’tUse Avatar Group for a single person or entity	Only one Avatar is shown; use the Avatar on its own.

How to Use

Optionally add text labels to Avatars

Text labels are not provided directly with an Avatar, but are recommended when space allows. Customize labels as needed.

Adding interactivity to an Avatar

Combine an avatar with a Button Compound to add interaction. This provides interactive states and accessibility.

Since an Avatar is non-interactive by default, use a Tooltip when the Avatar is focusable by adding tabIndex={0}. A text label next to the Avatar is still the preferred option.

Caution

Don’t make isolated changes to an Avatar’s shape

Shape is consistent when representing a category of entities. Deviating from this confuses users.

Don’t

Content

Avatar will always display initials when no image is provided.

Keyboard Interaction

The default Avatar and Avatar Group, do not have any keyboard interactions.

Code

Implementation
Avatar Props
AvatarGroup Props

Common Examples

import { Avatar } from "@servicetitan/anvil2";

const ExampleComponent = () => {
  return <Avatar name="Albert Einstein" />;
};

Changing the avatar colors

Avatar colors can be changed using the color prop. Internally, the color could be adjusted in order to ensure low vision and colorblind users can read the text.

Showing online status on avatars

Set the status prop to "online" or "offline" to add an indicator to the avatar.

Avatar image and name

The content within an avatar will change based on the name and image props provided. If an image is provided, and does not fail to load, it will be displayed.If no image is provided, or it fails to load, two characters of the name value will show instead:

If name is a single word, the first two characters will be used
If name is multiple words, the first characters of the first and last words are used

Avatar with image and name

Avatar with name only

Stacking avatars in a group

Avatars can be grouped using the Avatar.Group component. They will overlap slightly, with the last Avatar component child on top.

Avatar as a button

To make an avatar interactive, wrap it with a ButtonCompound with shape="circular". This will add a button element around the avatar which can be used for tab focus and interactions.

<Avatar
  name="Albert Einstein"
  color="red"
  size="small"
  status="online"
  image="https://example.com/image.jpg"
/>

`Avatar` Props

string

required

This string will be used for alt text and screenreaders even if it is not visible.

string

"small" | "medium" | "large"

default:"medium"

"online" | "offline"

<AvatarGroup max={3}>
  <Avatar name="Priya Patel" />
  <Avatar name="Marcus Chen" />
  <Avatar name="Sofia Rodriguez" />
  <Avatar name="Kwame Okafor" />
</AvatarGroup>

`AvatarGroup` Props

number

The group will truncate after showing this maximum number of avatars, and will display the number of additional avatars (e.g. “+3”).

Concepts & Guidelines

Anvil2

Resources

Avatar - Web

Anatomy

Options

Image

Initials

Custom background colors

Sizes

Status

Grouping

Status in groups

Usage Guidelines

How to Use

Optionally add text labels to Avatars

Adding interactivity to an Avatar

Only use a Tooltip when also adding interactivity

Don’t make isolated changes to an Avatar’s shape

Content

Keyboard Interaction

Code

Common Examples

Changing the avatar colors

Showing online status on avatars

Avatar image and name

Avatar with image and name

Avatar with name only

Stacking avatars in a group

Avatar as a button

`Avatar` Props

`AvatarGroup` Props

​Anatomy

​Options

​Image

​Initials

​Custom background colors

​Sizes

​Status

​Grouping

​Status in groups

​Usage Guidelines

​How to Use

​Optionally add text labels to Avatars

​Adding interactivity to an Avatar

​Only use a Tooltip when also adding interactivity

​Don’t make isolated changes to an Avatar’s shape

​Content

​Keyboard Interaction

​Code

​Common Examples

​Changing the avatar colors

​Showing online status on avatars

​Avatar image and name

​Avatar with image and name

​Avatar with name only

​Stacking avatars in a group

​Avatar as a button

​Avatar Props

​AvatarGroup Props

Anatomy

Options

Image

Initials

Custom background colors

Sizes

Status

Grouping

Status in groups

Usage Guidelines

How to Use

Optionally add text labels to Avatars

Adding interactivity to an Avatar

Only use a Tooltip when also adding interactivity

Don’t make isolated changes to an Avatar’s shape

Content

Keyboard Interaction

Code

Common Examples

Changing the avatar colors

Showing online status on avatars

Avatar image and name

Avatar with image and name

Avatar with name only

Stacking avatars in a group

Avatar as a button

`Avatar` Props

`AvatarGroup` Props