> ## 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](#dont-make-isolated-changes-to-an-avatars-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://mintlify.s3.us-west-1.amazonaws.com/servicetitan/images/docs/web/components/avatar/web/avatar-how-label.png)

#### 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://mintlify.s3.us-west-1.amazonaws.com/servicetitan/images/docs/web/components/avatar/web/avatar-how-compound.png)

#### 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://mintlify.s3.us-west-1.amazonaws.com/servicetitan/images/docs/web/components/avatar/web/avatar-how-tooltip-caution.png)

> [!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://mintlify.s3.us-west-1.amazonaws.com/servicetitan/images/docs/web/components/avatar/web/avatar-how-shape-dont.png)

> [!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

**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;
```

**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"`

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