## Usage

The `<Avatar />` component is used to visually represent a user in your application.

```tsx live
<Avatar src={`https://i.pravatar.cc/150?img=1`} name="Jane Doe" />
```

## Variants

Below are the three variants that can be rendered depending on what prop values have been provided to the component.

- **Placeholder** - Used when no data has been submitted for a user.
- **Initials** - Used when we know at least one of the user's names and an image has not been uploaded or is not working. The first name and last name initial is used for all sizes except for the `xsmall` size where it will only show the first name initial.
- **Image** - Used when the user has uploaded a working image to the application. Try updating the `src` prop in the code example below with an invalid image path/url.

```tsx live
<Flex flexDirection="row" gap="medium">
  <Avatar />
  <Avatar name="John Doe" />
  <Avatar src={`https://i.pravatar.cc/150`} name="John Doe" />
</Flex>
```

## Sizes

Avatars are available in all sizes using the available `size` prop tokens below.

- `xlarge` - Used when a page or component is primarily centred around a single user, e.g. on a user profile page.
- `large` - Used when a page or component contains a lot of elements and the avatar needs visual prominence.
- `medium` - Used primarily within components when surrounding UI elements harmonise with it proportionally. Commonly used in dropdowns, tables, lists or tight UI compositions.
- `small` - When the medium size is too large, this size can be used in its place. Commonly used in dropdowns, tables, lists or tight UI compositions.
- `xsmall` - When the small size is too large, this size can be used in its place. Commonly used in dropdowns, tables, lists or tight UI compositions. The xsmall size will only ever display the first initial due to the limited space available.

```tsx live
<Flex flexDirection="row" gap="medium">
  <Avatar src={`https://i.pravatar.cc/150`} size={{ xsmall: 'xsmall', large: 'xlarge' }} />
  <Avatar src={`https://i.pravatar.cc/150`} size={{ xsmall: 'xsmall', large: 'large' }} />
  <Avatar src={`https://i.pravatar.cc/150`} size={{ xsmall: 'xsmall', large: 'medium' }} />
  <Avatar src={`https://i.pravatar.cc/150`} size={{ xsmall: 'xsmall', large: 'small' }} />
  <Avatar src={`https://i.pravatar.cc/150`} size={{ xsmall: 'xsmall', large: 'xsmall' }} />
</Flex>
```

## Disabled

Avatars can be disabled to indicate that a user or entity is unavailable due to insufficient setup or deactivation within the application.

```tsx live
<Flex flexDirection="row" gap="medium">
  <Avatar disabled />
  <Avatar name="Disabled Avatar" disabled />
  <Avatar src="https://i.pravatar.cc/150" name="John Doe" disabled />
</Flex>
```

## Retry

When an avatar image fails to load, the component automatically retries loading it using exponential backoff. You can customize the retry behavior using the `maxRetries` and `retryDelay` props.

- `maxRetries` - Maximum number of retry attempts. Defaults to `3`.
- `retryDelay` - Initial delay in milliseconds before the first retry. Defaults to `1000ms`. Each subsequent retry doubles the delay.

```tsx live
<Flex flexDirection="row" gap="medium">
  <Avatar src="https://invalid-url.com/image.jpg" name="Custom Retry" maxRetries={5} retryDelay={500} />
  <Avatar src="https://invalid-url.com/image.jpg" name="Default Retry" />
</Flex>
```

## Stacked avatars

Use the `<AvatarGroup/>` component when you need to stack multiple avatars next to each other. You can control both the spacing between avatars and the avatar size with the `size` prop.

```tsx live
<Flex flexDirection="column" gap="large">
  <AvatarGroup size="xlarge">
    <Avatar name="Tony Stark" />
    <Avatar name="Bruce Banner" />
    <Avatar name="Natasha Romanoff" />
    <Avatar name="Spider-man" />
  </AvatarGroup>

  <AvatarGroup size="large">
    <Avatar name="Tony Stark" />
    <Avatar name="Bruce Banner" />
    <Avatar name="Natasha Romanoff" />
    <Avatar name="Spider-man" />
  </AvatarGroup>

  <AvatarGroup size="medium">
    <Avatar name="Tony Stark" />
    <Avatar name="Bruce Banner" />
    <Avatar name="Natasha Romanoff" />
    <Avatar name="Spider-man" />
  </AvatarGroup>

  <AvatarGroup size="small">
    <Avatar name="Tony Stark" />
    <Avatar name="Bruce Banner" />
    <Avatar name="Natasha Romanoff" />
    <Avatar name="Spider-man" />
  </AvatarGroup>

  <AvatarGroup size="xsmall">
    <Avatar name="Tony Stark" />
    <Avatar name="Bruce Banner" />
    <Avatar name="Natasha Romanoff" />
    <Avatar name="Thor Odinson" />
  </AvatarGroup>
</Flex>
```

### Responsive size

The `<AvatarGroup/>` also supports the [responsive prop syntax](/foundations/responsive-layouts/#responsive-prop-syntax) being passed to the `size` prop. This allows control over the avatar sizes across different device widths.

```tsx live
<AvatarGroup size={{ xsmall: 'xsmall', small: 'small', medium: 'medium', large: 'large', xlarge: 'xlarge' }}>
  <Avatar name="Tony Stark" />
  <Avatar name="Bruce Banner" />
  <Avatar name="Natasha Romanoff" />
  <Avatar name="Spider-man" />
</AvatarGroup>
```

### Cap

You can control all overflowing avatars using the `cap` prop. In this example, there are a total of `10` users with a cap of `5` being set. The `5` remaining users are subsequently hidden with the overflow element.

```tsx live
<AvatarGroup cap={5}>
  <Avatar name="Tony Stark" />
  <Avatar name="Bruce Banner" />
  <Avatar name="Natasha Romanoff" />
  <Avatar name="Peter Parker" />
  <Avatar name="Steve Rogers" />
  <Avatar name="Thor Odinson" />
  <Avatar name="Scott Lang" />
  <Avatar name="King T'Challa" />
  <Avatar name="Clint Barton" />
  <Avatar name="Bucky Barnes" />
</AvatarGroup>
```

When the `+n` count exceeds the available space in its surrounding circle, an ellipsis (...) will be used instead of a number.

- For avatar sizes `xsmall` and `small`, the ellipsis will be visible when the remaining `+n` count exceeds 9.
- For avatar sizes `medium`, `large` and `xlarge`, the ellipsis will be visible when the remaining `+n` count exceeds 999.

```tsx live
<AvatarGroup cap={5} size="small">
  <Avatar name="Tony Stark" />
  <Avatar name="Bruce Banner" />
  <Avatar name="Natasha Romanoff" />
  <Avatar name="Peter Parker" />
  <Avatar name="Steve Rogers" />
  <Avatar name="Thor Odinson" />
  <Avatar name="Scott Lang" />
  <Avatar name="King T'Challa" />
  <Avatar name="Clint Barton" />
  <Avatar name="Jessica Jones" />
  <Avatar name="Luke Cage" />
  <Avatar name="Adam Warlock" />
  <Avatar name="Gamora Zen Whoberi Ben Titan" />
  <Avatar name="Drax" />
  <Avatar name="Rocket" />
</AvatarGroup>
```

## Accessibility

If the avatar is purely decorative or accompanied by visible text that describes the user, you can hide it from screen readers by setting `aria-hidden` to `true`.

```tsx live
const avatarWithName = <Avatar aria-hidden name="John Doe" />;
const avatarWithSrc = <Avatar aria-hidden src="https://i.pravatar.cc/150?img=1" />;
const avatarWithNameAndSrc = <Avatar aria-hidden name="John Doe" src="https://i.pravatar.cc/150?img=2" />;

const examples = [avatarWithName, avatarWithSrc, avatarWithNameAndSrc];

return (
  <Flex flexDirection="column" gap="small">
    {examples.map((example, index) => (
      <RailTrack alignItems="center" key={index} railLeft={example} spacing="xxsmall">
        <Text>John Doe</Text>
      </RailTrack>
    ))}
  </Flex>
);
```

Avatar

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources

Indicates whether the element is exposed to an accessibility API.

aria-hidden

Used for the image's alt attribute, and for the name initials when there is no image (`src`) provided.

name

The size of the avatar. Defaults to `medium`.

size

disabled

Maximum number of retry attempts for loading the avatar image. Defaults to 3.

maxRetries

Initial delay in milliseconds before first retry. Defaults to 1000.

retryDelay

children

The size of the avatar within the group. Defaults to `medium`.

AvatarGroup

Prop	Required	Description	Type
`aria-hidden`	—	Indicates whether the element is exposed to an accessibility API.	false \| true \| "true" \| "false"
`name`	—	Used for the image's alt attribute, and for the name initials when there is no image (src) provided.	string
`size`	—	The size of the avatar. Defaults to medium.	"xsmall" \| "small" \| "medium" \| "large" \| "xlarge"Supports responsive prop syntax
`disabled`	—	Optionally set the avatar as disabled.	boolean
`src`	—	Optionally set the avatar image.	string
`maxRetries`	—	Maximum number of retry attempts for loading the avatar image. Defaults to 3.	number
`retryDelay`	—	Initial delay in milliseconds before first retry. Defaults to 1000.	number

Prop	Required	Description	Type
`children`	✅	Pass in <Avatar />s as children.	ReactElement<AvatarProps, string \| JSXElementConstructor<any>>[]
`aria-hidden`	—	Indicates whether the element is exposed to an accessibility API.	false \| true \| "true" \| "false"
`size`	—	The size of the avatar within the group. Defaults to medium.	"xsmall" \| "small" \| "medium" \| "large" \| "xlarge"Supports responsive prop syntax
`cap`	—	Max number of avatars to be displayed.	number