> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.servicetitan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Avatar - Web

> Avatars visually represent an entity, typically a person or business.

> [!NOTE]
>
> For development, import `Avatar` from
> `@servicetitan/anvil2`. For design, find it in the
> [Anvil2 file](https://www.figma.com/design/xaNQsvRKczoxu7pj0M6QT8/Anvil2-v3?node-id=173-5236).

![](https://mintcdn.com/servicetitan/uz2PQSvO75TRhQ38/images/docs/web/components/shared/avatar-overview.png?fit=max\&auto=format\&n=uz2PQSvO75TRhQ38\&q=85\&s=30b012f695ae2a171d285143b6c866b8)

## Anatomy

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

![Anatomy of an
Avatar](https://mintcdn.com/servicetitan/ABmJyJBQtPOXixkz/images/docs/web/components/avatar/design/anatomy-of-an-avatar.png?fit=max\&auto=format\&n=ABmJyJBQtPOXixkz\&q=85\&s=a2e3b6c0e5fae6fe8bc116f7593c767e)

1. Avatar body
2. Status indicator (Optional)
3. Avatar Group

## Options

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

### Image

avatar-image

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-image?file=src/App.tsx)

```tsx lines theme={null}
import { Avatar, Flex } from "@servicetitan/anvil2";
import dog01 from "../assets/dog-01.png";
import dog02 from "../assets/dog-02.png";

function App() {
  return (
    <Flex gap="6" justifyContent="center">
      <Avatar image={dog01} name="Dog01" />
      <Avatar image={dog02} name="Dog02" />
    </Flex>
  );
}

export default App;
```

### Initials

When an image is not used, the avatar displays initials derived from the name, calculated based on specific rules.

avatar-name-two-words

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-name-two-words?file=src/App.tsx)

```tsx lines theme={null}
import { Avatar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex justifyContent="center">
      <Avatar name="Allen Thor Grace" />
    </Flex>
  );
}

export default App;
```

When two or more words are used, the first letter of the first two words is used.

avatar-name-one-word

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-name-one-word?file=src/App.tsx)

```tsx lines theme={null}
import { Avatar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex justifyContent="center">
      <Avatar name="Jason" />
    </Flex>
  );
}

export default App;
```

When only one word is provided in the name, the first two letters are used.

avatar-name-small

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-name-small?file=src/App.tsx)

```tsx lines theme={null}
import { Avatar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex justifyContent="center" style={{ padding: "4px" }}>
      <Avatar size="small" name="Ben" />
    </Flex>
  );
}

export default App;
```

On 'small' Avatars, only the first letter is used regardless of what name is used.

### Custom background colors

avatar-color

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-color?file=src/App.tsx)

```tsx lines theme={null}
import { Avatar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex gap="2">
      <Avatar color="purple" name="James" size="large" />
      <Avatar color="#0066CC" name="Nick" size="large" />
      <Avatar color="rgb(100,100,50)" name="Ben" size="large" />
    </Flex>
  );
}

export default App;
```

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

avatar-size

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-size?file=src/App.tsx)

```tsx lines theme={null}
import { Avatar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex gap="3" justifyContent="center" alignItems="center">
      <Avatar name="Small" size="small" />
      <Avatar name="Medium" size="medium" />
      <Avatar name="Large" size="large" />
    </Flex>
  );
}

export default App;
```

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

### Status

Avatars can also convey an online or offline status.

avatar-status

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-status?file=src/App.tsx)

```tsx lines theme={null}
import { Avatar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex gap="2">
      <Avatar status="online" name="Ryan" size="large" />
      <Avatar status="offline" name="Patrick" size="large" />
      <Avatar name="Derek" size="large" />
    </Flex>
  );
}

export default App;
```

### Grouping

avatar-group

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-group?file=src/App.tsx)

```tsx lines theme={null}
import { Avatar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex direction="column" gap={4}>
      <Avatar.Group>
        <Avatar size="large" name="James M." />
        <Avatar size="large" name="Ben R." />
        <Avatar size="large" name="Adam G." />
      </Avatar.Group>
      <Avatar.Group>
        <Avatar size="medium" name="James M." />
        <Avatar size="medium" name="Ben R." />
        <Avatar size="medium" name="Adam G." />
      </Avatar.Group>
      <Avatar.Group>
        <Avatar size="small" name="James M." />
        <Avatar size="small" name="Ben R." />
        <Avatar size="small" name="Adam G." />
      </Avatar.Group>
    </Flex>
  );
}

export default App;
```

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.

avatar-group-max

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-group-max?file=src/App.tsx)

```tsx lines theme={null}
import { Avatar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex justifyContent="center">
      <Avatar.Group max={3}>
        <Avatar name="James M." />
        <Avatar name="Ben R." />
        <Avatar name="Adam G." />
        <Avatar name="Adam G." />
        <Avatar name="Adam G." />
        <Avatar name="Adam G." />
        <Avatar name="Adam G." />
        <Avatar name="Adam G." />
      </Avatar.Group>
    </Flex>
  );
}

export default App;
```

### Status in groups

avatar-group-status

[StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-group-status?file=src/App.tsx)

```tsx lines theme={null}
import { Avatar, Flex } from "@servicetitan/anvil2";

function App() {
  return (
    <Flex justifyContent="center">
      <Avatar.Group max={3}>
        <Avatar status="online" name="James M." />
        <Avatar status="offline" name="Ben R." />
        <Avatar status="online" name="Adam G." />
        <Avatar status="online" name="Adam G." />
        <Avatar status="offline" name="Adam G." />
        <Avatar status="offline" name="Adam G." />
        <Avatar status="online" name="Adam G." />
        <Avatar status="online" name="Adam G." />
      </Avatar.Group>
    </Flex>
  );
}

export default App;
```

## 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](#don%E2%80%99t-make-isolated-changes-to-an-avatar%E2%80%99s-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.

![Avatar how
label](https://mintcdn.com/servicetitan/ABmJyJBQtPOXixkz/images/docs/web/components/avatar/design/avatar-how-label.png?fit=max\&auto=format\&n=ABmJyJBQtPOXixkz\&q=85\&s=116f9a62b4507a03b892c62eed044112)

#### Adding interactivity to an Avatar

Combine an avatar with a [Button Compound](https://anvil.servicetitan.com/docs/components/button/web.md#button-compound) to add interaction. This provides interactive states and accessibility.

![Avatar how
compound](https://mintcdn.com/servicetitan/ABmJyJBQtPOXixkz/images/docs/web/components/avatar/design/avatar-how-compound.png?fit=max\&auto=format\&n=ABmJyJBQtPOXixkz\&q=85\&s=2762a30b847d08fbe8aee727e94a5215)

#### Only use a Tooltip when also adding interactivity

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.

![Avatar how tooltip
caution](https://mintcdn.com/servicetitan/ABmJyJBQtPOXixkz/images/docs/web/components/avatar/design/avatar-how-tooltip-caution.png?fit=max\&auto=format\&n=ABmJyJBQtPOXixkz\&q=85\&s=f98e4940f39760515ec2995fe257d6b2)

> [!WARNING]
>
> **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.

![Avatar how shape
don't](https://mintcdn.com/servicetitan/ABmJyJBQtPOXixkz/images/docs/web/components/avatar/design/avatar-how-shape-dont.png?fit=max\&auto=format\&n=ABmJyJBQtPOXixkz\&q=85\&s=a1debfcbb9f3d041f704fd67c1ee5830)

> [!CAUTION]
>
> **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

> [tab] Implementation
>
> avatar-playground
>
> [StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-playground?file=src/App.tsx)
>
> ```tsx lines expandable theme={null}
> import { Avatar } from "@servicetitan/anvil2";
>
> function App() {
>   return (
>     <Avatar name="Derek Watson" color="#e41c38" status="online" size="large" />
>   );
> }
>
> export default App;
> ```
>
> ## Common Examples
>
> ```tsx theme={null}
> 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.
>
> avatar-color
>
> [StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-color?file=src/App.tsx)
>
> ```tsx lines expandable theme={null}
> import { Avatar, Flex } from "@servicetitan/anvil2";
>
> function App() {
>   return (
>     <Flex gap="2">
>       <Avatar color="purple" name="James" size="large" />
>       <Avatar color="#0066CC" name="Nick" size="large" />
>       <Avatar color="rgb(100,100,50)" name="Ben" size="large" />
>     </Flex>
>   );
> }
>
> export default App;
> ```
>
> ### Showing online status on avatars
>
> Set the `status` prop to `"online"` or `"offline"` to add an indicator to the avatar.
>
> avatar-status
>
> [StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-status?file=src/App.tsx)
>
> ```tsx lines expandable theme={null}
> import { Avatar, Flex } from "@servicetitan/anvil2";
>
> function App() {
>   return (
>     <Flex gap="2">
>       <Avatar status="online" name="Ryan" size="large" />
>       <Avatar status="offline" name="Patrick" size="large" />
>       <Avatar name="Derek" size="large" />
>     </Flex>
>   );
> }
>
> export default App;
> ```
>
> ### 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-image-and-name
>
> [StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-image-and-name?file=src/App.tsx)
>
> ```tsx lines theme={null}
> import { Avatar } from "@servicetitan/anvil2";
> import Logo_block from "../assets/Logo_block.jpg";
>
> function App() {
>   return <Avatar image={Logo_block} name="Titan" />;
> }
>
> export default App;
> ```
>
> ### Avatar with name only
>
> avatar-name-only
>
> [StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-name-only?file=src/App.tsx)
>
> ```tsx lines theme={null}
> import { Avatar, Flex } from "@servicetitan/anvil2";
>
> function App() {
>   return (
>     <Flex gap="2">
>       <Avatar name="Titan" />
>       <Avatar name="Service Titan" />
>     </Flex>
>   );
> }
>
> export default App;
> ```
>
> ### 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-group
>
> [StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-group?file=src/App.tsx)
>
> ```tsx lines expandable theme={null}
> import { Avatar, Flex } from "@servicetitan/anvil2";
>
> function App() {
>   return (
>     <Flex direction="column" gap={4}>
>       <Avatar.Group>
>         <Avatar size="large" name="James M." />
>         <Avatar size="large" name="Ben R." />
>         <Avatar size="large" name="Adam G." />
>       </Avatar.Group>
>       <Avatar.Group>
>         <Avatar size="medium" name="James M." />
>         <Avatar size="medium" name="Ben R." />
>         <Avatar size="medium" name="Adam G." />
>       </Avatar.Group>
>       <Avatar.Group>
>         <Avatar size="small" name="James M." />
>         <Avatar size="small" name="Ben R." />
>         <Avatar size="small" name="Adam G." />
>       </Avatar.Group>
>     </Flex>
>   );
> }
>
> export default App;
> ```
>
> ### 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-button
>
> [StackBlitz demo](https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples/avatar-button?file=src/App.tsx)
>
> ```tsx lines expandable theme={null}
> import { Avatar, ButtonCompound } from "@servicetitan/anvil2";
>
> function App() {
>   return (
>     <ButtonCompound shape="circular" onClick={() => alert("Clicked!")}>
>       <Avatar name="Rose Tico" size="large" status="online" />
>     </ButtonCompound>
>   );
> }
>
> export default App;
> ```

> [tab] Avatar Props
>
> ```tsx theme={null}
> <Avatar
>   name="Albert Einstein"
>   color="red"
>   size="small"
>   status="online"
>   image="https://example.com/image.jpg"
> />
> ```
>
> ## `Avatar` Props
>
> **name** `string` *required*
>
> This string will be used for alt text and screenreaders even if it is not
> visible.
>
> **color** `string`
>
> **image** `string`
>
> **size** `"small" | "medium" | "large"` (default: medium)
>
> **status** `"online" | "offline"`

> [tab] AvatarGroup Props
>
> ```tsx theme={null}
> <AvatarGroup max={3}>
>   <Avatar name="Priya Patel" />
>   <Avatar name="Marcus Chen" />
>   <Avatar name="Sofia Rodriguez" />
>   <Avatar name="Kwame Okafor" />
> </AvatarGroup>
> ```
>
> ## `AvatarGroup` Props
>
> **max** `number`
>
> The group will truncate after showing this maximum number of avatars, and will
> display the number of additional avatars (e.g. "+3").


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.