> ## 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 – Design

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

export const LiveCode = ({children, customHeight, clickToLoad, example, fullWidth, fullHeight, hideCodeInLiveCode, screenshot, screenshotOnly, showCode: showCodeProp}) => {
  const SCREENSHOTS_BASE = "https://servicetitan.github.io/anvil2-docs-live-code/screenshots";
  const STACKBLITZ_BASE = "https://stackblitz.com/github/servicetitan/anvil2-docs-live-code/tree/main/examples";
  const [showCodeBlock, setShowCodeBlock] = useState(showCodeProp ?? false);
  const [isLocalOverride, setIsLocalOverride] = useState(false);
  useEffect(() => {
    const examplePath = `/images/live-code-screenshots-tmp/${example}.png`;
    fetch(examplePath, {
      method: "HEAD"
    }).then(r => {
      if (r.ok) setIsLocalOverride(true);
    }).catch(() => {});
  }, [example]);
  const screenshotBase = isLocalOverride ? "/images/live-code-screenshots-tmp" : SCREENSHOTS_BASE;
  if (screenshotOnly) {
    return <Frame className="flex flex-col">
        <div className="flex dark:hidden" style={{
      justifyContent: "center",
      alignItems: "center",
      width: fullWidth ? "100%" : "50%",
      minHeight: fullHeight ? "284px" : undefined,
      background: "#FFFFFF"
    }}>
          <img srcset={`${screenshotBase}/${example}.png, ${screenshotBase}/${example}-2x.png 2x`} src={`${screenshotBase}/${example}.png`} alt={example} noZoom />
        </div>
        <div className="hidden dark:flex" style={{
      justifyContent: "center",
      alignItems: "center",
      width: fullWidth ? "100%" : "50%",
      minHeight: fullHeight ? "284px" : undefined,
      background: "#141414"
    }}>
          <img srcset={`${screenshotBase}/${example}-dark.png, ${screenshotBase}/${example}-dark-2x.png 2x`} src={`${screenshotBase}/${example}-dark.png`} alt={example} noZoom />
        </div>
      </Frame>;
  }
  if (screenshot) {
    return <Frame className="flex flex-col -mb-2">
        <div className="flex dark:hidden bg-white dark:bg-codeblock border border-gray-950/10 dark:border-white/10 dark:twoslash-dark rounded-2xl overflow-hidden" style={{
      justifyContent: "center",
      alignItems: "center",
      width: fullWidth ? "100%" : "50%",
      minHeight: fullHeight ? "284px" : undefined
    }}>
          <img srcset={`${screenshotBase}/${example}.png, ${screenshotBase}/${example}-2x.png 2x`} src={`${screenshotBase}/${example}.png`} alt={example} noZoom />
        </div>

        <div className="hidden dark:flex bg-white dark:bg-codeblock border border-gray-950/10 dark:border-white/10 dark:twoslash-dark rounded-2xl overflow-hidden" style={{
      background: "#141414",
      justifyContent: "center",
      alignItems: "center",
      width: fullWidth ? "100%" : "50%",
      minHeight: fullHeight ? "284px" : undefined
    }}>
          <img srcset={`${screenshotBase}/${example}-dark.png, ${screenshotBase}/${example}-dark-2x.png 2x`} src={`${screenshotBase}/${example}-dark.png`} alt={example} noZoom />
        </div>

        <div className="flex justify-end items-center text-xs py-2 px-1 gap-4">
          {!showCodeProp ? <button className="inline-flex justify-end items-center text-gray-700 dark:text-gray-50 hover:text-blue-500 dark:hover:text-blue-300 transition-colors group self-end gap-1 cursor-pointer" onClick={() => setShowCodeBlock(!showCodeBlock)} style={{
      appearance: "none"
    }}>
              <Icon icon="code" size="12px" className="group-hover:bg-blue-500 dark:group-hover:bg-blue-300" />
              <span>{showCodeBlock ? "Hide code" : "Show code"}</span>
            </button> : null}

          <a className="inline-flex justify-end items-center hover:text-blue-500 dark:hover:text-blue-300 transition-colors group self-end gap-1" href={`${STACKBLITZ_BASE}/${example}?file=src/App.tsx`} target="_blank" rel="noreferrer">
            <Icon icon="bolt" size="12px" className="group-hover:bg-blue-500 dark:group-hover:bg-blue-300" />
            <span>StackBlitz demo</span>
          </a>
        </div>

        <div className="grid transition-[grid-template-rows] duration-300 ease-in-out overflow-auto overflow-y-hidden overflow-x-auto" style={showCodeBlock ? {
      gridTemplateRows: "1fr"
    } : {
      gridTemplateRows: "0fr"
    }}>
          <div style={{
      minHeight: 0,
      overflowX: "auto",
      overflowY: "hidden",
      marginBlockStart: "-1.25rem",
      marginBlockEnd: "-1.5rem"
    }}>
            {children}
          </div>
        </div>
      </Frame>;
  } else {
    return <div style={{
      display: "flex",
      width: fullWidth ? "100%" : "50%",
      minHeight: customHeight ? customHeight : "316px",
      resize: "vertical",
      overflow: "auto"
    }}>
        <iframe title={example} style={{
      flex: 1,
      width: fullWidth ? "100%" : "50%",
      minHeight: customHeight ? customHeight : "316px"
    }} src={`${STACKBLITZ_BASE}/${example}?embed=1&hideNavigation=1&hideExplorer=1&terminalHeight=0&file=src/App.tsx${clickToLoad ? "&ctl=1" : ""}${hideCodeInLiveCode ? "&view=preview" : ""}`} allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking" sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts" />
      </div>;
  }
};

export const CodePreviewPlaceholder = ({double, fullWidth}) => {
  const single = <div style={{
    width: fullWidth ? "100%" : "50%",
    borderRadius: "1rem",
    display: "flex",
    padding: "1rem",
    flexDirection: "column",
    gap: "0.5rem",
    height: "10rem",
    marginBlockEnd: "1rem"
  }} className="border-width-default border-color-subdued">
      <div className="bg-strong border-radius-large" style={{
    width: "100%",
    flexGrow: "1"
  }} />
      <div className="bg-strong border-radius-large" style={{
    width: "100%",
    flexGrow: "1"
  }} />
    </div>;
  return double ? <div style={{
    display: "flex",
    gap: "1rem"
  }}>
      {single}
      {single}
    </div> : single;
};

<Frame>
  <div className="w-full h-full bg-[#FFFFFF] p-2 rounded flex items-center justify-center">
    <img noZoom src="https://mintcdn.com/servicetitan/uz2PQSvO75TRhQ38/images/docs/web/components/shared/avatar-overview.png?fit=max&auto=format&n=uz2PQSvO75TRhQ38&q=85&s=30b012f695ae2a171d285143b6c866b8" width="272" height="96" data-path="images/docs/web/components/shared/avatar-overview.png" />
  </div>
</Frame>

## Anatomy

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

<Frame>
  <div className="w-full h-full bg-[#FFFFFF] p-2 rounded flex items-center justify-center">
    <img
      src="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"
      alt="Anatomy of an
Avatar"
      width="300"
      height="288"
      data-path="images/docs/web/components/avatar/design/anatomy-of-an-avatar.png"
    />
  </div>
</Frame>

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

<LiveCode example="avatar-image" screenshot fullWidth>
  ```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;
  ```
</LiveCode>

### Initials

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

<LiveCode example="avatar-name-two-words" screenshot fullWidth>
  ```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;
  ```
</LiveCode>

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

<LiveCode example="avatar-name-one-word" screenshot fullWidth>
  ```tsx lines theme={null}
  import { Avatar, Flex } from "@servicetitan/anvil2";

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

  export default App;
  ```
</LiveCode>

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

<LiveCode example="avatar-name-small" screenshot fullWidth>
  ```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;
  ```
</LiveCode>

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

### Custom background colors

<LiveCode example="avatar-color" screenshot fullWidth>
  ```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;
  ```
</LiveCode>

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

<LiveCode example="avatar-size" screenshot fullWidth>
  ```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;
  ```
</LiveCode>

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

### Status

Avatars can also convey an online or offline status.

<LiveCode example="avatar-status" screenshot fullWidth>
  ```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;
  ```
</LiveCode>

### Grouping

<LiveCode example="avatar-group" screenshot fullWidth>
  ```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;
  ```
</LiveCode>

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.

<LiveCode example="avatar-group-max" screenshot fullWidth>
  ```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;
  ```
</LiveCode>

### Status in groups

<LiveCode example="avatar-group-status" screenshot fullWidth>
  ```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;
  ```
</LiveCode>

## Usage Guidelines

### When to Use

Avatars are appropriate when referencing a person. They also represent other entities such as businesses. Follow local standards for business entity representation.

### When not to use

Avatars should be avoided to display icons or emojis, and an element such as a Button may be more appropriate.

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

<Frame>
  <div className="w-full h-full bg-[#FFFFFF] p-2 rounded flex items-center justify-center">
    <img
      src="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"
      alt="Avatar how
label"
      width="252"
      height="336"
      data-path="images/docs/web/components/avatar/design/avatar-how-label.png"
    />
  </div>
</Frame>

#### Adding interactivity to an Avatar

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

<Frame>
  <div className="w-full h-full bg-[#FFFFFF] p-2 rounded flex items-center justify-center">
    <img
      src="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"
      alt="Avatar how
compound"
      width="456"
      height="156"
      data-path="images/docs/web/components/avatar/design/avatar-how-compound.png"
    />
  </div>
</Frame>

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

<Frame>
  <div className="w-full h-full bg-[#FFFFFF] p-2 rounded flex items-center justify-center">
    <img
      src="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"
      alt="Avatar how tooltip
caution"
      width="287"
      height="160"
      data-path="images/docs/web/components/avatar/design/avatar-how-tooltip-caution.png"
    />
  </div>
</Frame>

<Warning>**Caution**</Warning>

#### Don't make isolated changes to an Avatar's shape

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

<Frame>
  <div className="w-full h-full bg-[#FFFFFF] p-2 rounded flex items-center justify-center">
    <img
      src="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"
      alt="Avatar how shape
don't"
      width="272"
      height="96"
      data-path="images/docs/web/components/avatar/design/avatar-how-shape-dont.png"
    />
  </div>
</Frame>

<Danger>**Don't**</Danger>

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