# Avatar

A graphical representation of a user or entity - usually a photo or initials

Tabs: [Guidelines](/components/web/avatar/avatar.guidelines.md) · [Code](/components/web/avatar/avatar.code.md)

## Features

- Shows initials if no image source is provided.

- Generates a background color if no image source is provided.

- Prevents content flashing by checking if the image source exists.

## When to use

At Pleo, we primarily use avatars to represent a user, either with a profile picture or initials if a picture hasn't been provided. We also use them to represent merchants in expenses or subscriptions.

## Examples

### Sizes

The component comes in a few different sizes.

```tsx
<Inline space={12}>
    <Avatar name="Jeppe Rindom" size={24} src={jeppe} />
    <Avatar name="Jeppe Rindom" size={40} src={jeppe} />
    <Avatar name="Jeppe Rindom" size={48} src={jeppe} />
    <Avatar name="Jeppe Rindom" size={72} src={jeppe} />
</Inline>
```

### Icons

In some cases we show an icon inside the avatar. An example of this is when we're representing merchants in expenses or subscriptions.

> When using only an icon inside the Avatar, be sure to set the `visuallyHiddenText` prop to support visually impaired users who rely on screen readers.

```tsx
<Avatar icon={<Wallet />} visuallyHiddenText="Wallet" />
```

### Fallback

If the image of the avatar fails to load, we show a fallback based on the provided name. The name is used to generate initials and a background color from a limited palette.

```tsx
<Avatar name="Jeppe Rindom" src="some-broken-link" />
```

### Outline

We show an outline around avatars when stacked in an [`AvatarGroup`](#avatargroup) or simply to create contrast when presented on a none white background.

```tsx
<Inline css={{backgroundColor: tokens.colorBackgroundStaticLoudest, padding: tokens.spacing12}}>
    <Avatar outlined name="Jeppe Rindom" src={jeppe} />
</Inline>
```

### Disabled

A disabled version of the avatar can be used e.g. when a user has been deactivated, indicating that their profile is inactive and preventing any confusion about their current status.

```tsx
<Avatar name="Jeppe Rindom" state="disabled" src={jeppe}>
    <Avatar.Badge visuallyHiddenText="Deactivated user" icon={<TrashClock />} />
</Avatar>
```

### Placeholder

A placeholder avatar can be used when data is unavailable, such as when an employee is invited to join a company in Pleo but has not yet onboarded. In this case, the placeholder prevents confusion by indicating that a profile exists but is not yet fully set up.

```tsx
<Avatar state="placeholder" />
```

### Skeleton

Use a "skeleton" version of this component to display a loading state while data is being fetched. It provides a visual placeholder, giving users a preview of the UI structure before the actual content is loaded. This enhances the user experience by offering a more accurate representation of the final layout during data retrieval.

```tsx
<Avatar skeleton name="Jeppe Rindom" src={jeppe} />
```

## Badge

A companion component used to show an icon badge on top of an avatar. We use this in expenses to show categories or to reflect a private or pending purchase.

> While the badge *can* be used with all avatar sizes, it's only intended used for larger avatars as it will otherwise overlay too much of the avatar itself.

```tsx
<Avatar name="Jeppe Rindom" src={jeppe}>
    <Avatar.Badge
        visuallyHiddenText="Expense Category: Entertainment"
        icon={<CategoryEntertainment />}
    />
</Avatar>
```

### Examples

#### Variant

In some cases, you may want a badge to stand out if it's meant to communicate something of urgency or prominence. That can be done with a variant.

```tsx
<Avatar name="Jeppe Rindom" src={jeppe}>
    <Avatar.Badge
        visuallyHiddenText="Requires attention"
        icon={<SpeechBubble />}
        variant="attention"
    />
</Avatar>
```

## AvatarGroup

A companion component used to show a group/list of avatars.

```tsx
<AvatarGroup>
    <Avatar name="Jeppe Rindom" src={jeppe} />
    <Avatar name="Niccolo Perra" src={niccolo} />
</AvatarGroup>
```

### Examples

#### Size

If a size is provided to the avatar group, it will automatically be propagated down to the individual avatars within it.

```tsx
<AvatarGroup size={24}>
    <Avatar name="Jeppe Rindom" src={jeppe} />
    <Avatar name="Niccolo Perra" src={niccolo} />
</AvatarGroup>
```

#### Max

If you're working with dynamic data, it's possible to limit the amount of avatars shown. Additional avatars will be represented with an excess number component.

```tsx
<AvatarGroup max={2}>
    <Avatar name="Jeppe Rindom" src={jeppe} />
    <Avatar name="Niccolo Perra" src={niccolo} />
    <Avatar name="Pete Lacey" src="..." />
</AvatarGroup>
```

#### Stacked

We sometimes show avatars stacked on top of each other if there's limited horizontal space and/or it's more relevant *how many* people there are than precisely *who* they are.

```tsx
<AvatarGroup stacked max={2}>
    <Avatar name="Jeppe Rindom" src={jeppe} />
    <Avatar name="Niccolo Perra" src={niccolo} />
    <Avatar name="Pete Lacey" src="..." />
</AvatarGroup>
```

#### Large Datasets

When rendering avatar groups with potentially large datasets (hundreds or thousands of items), use the `items` and `renderAvatar` props instead of the `children` prop for better performance.

##### Usage

```tsx
<AvatarGroup
    items={[
        {id: '1', name: 'Jeppe Rindom', src: jeppe},
        {id: '2', name: 'Niccolo Perra', src: niccolo},
        {id: '3', name: 'Pete Lacey', src: '...'},
        // Could continue to hundreds of items
    ]}
    max={2}
    stacked
    size={40}
    renderAvatar={(employee, {size, outlined}) => (
        <Avatar name={employee.name} src={employee.src} size={size} outlined={outlined} />
    )}
/>
```

##### When to Use

- **Use `items` + `renderAvatar`** when you have dynamic lists, large datasets (100+ items), or need type safety
- **Use `children`** for small, static sets of avatars (< 10 items) where simplicity is preferred

## Accessibility

[WCAG success criterion 1.1.1 (Non-text Content, Level A)](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html) requires that all non-text content have a text alternative that conveys the same purpose.

Avatars are inherently visual, so it’s important to ensure their meaning is accessible to all users, including those using assistive technologies, such as screen readers.

### Images

When an Avatar contains an image, its alt text is automatically set to the Avatar's `name`. As a result, no additional action is required to ensure accessibility.

### Icons

For Avatars containing an icon, provide a text alternative using the `visuallyHiddenText` prop.

```tsx
<Avatar icon={<Wallet />} visuallyHiddenText="Wallet" />
```

The same applies to Avatar badges.

```tsx
<Avatar name="Jeppe Rindom" src={jeppe}>
    <Avatar.Badge
        visuallyHiddenText="Expense Category: Entertainment"
        icon={<CategoryEntertainment />}
    />
</Avatar>
```

### Decorative

If an Avatar’s meaning is already conveyed through accompanying text, it can be considered decorative. Set the `decorative` prop to hide it from screen readers and prevent redundant announcements.

```tsx
<Inline alignY="center" space={16}>
    <Avatar name="Jeppe Rindom" src={jeppe} decorative />
    <Text>Jeppe Rindom</Text>
</Inline>
```