---
title: Avatar
description: Avatar component is used to show a thumbnail representation of an individual or business in the interface. It can be a graphical representation or visual depiction, such as an image, initials, or an icon.
api_version: 2025-10
api_name: customer-account-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components/media/avatar
  md: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components/media/avatar.md
---

# Avatar

Avatar component is used to show a thumbnail representation of an individual or business in the interface. It can be a graphical representation or visual depiction, such as an image, initials, or an icon.

## Properties

* alt

  string

  An alternative text description that describe the image for the reader to understand what it is about or identify the user the avatar belongs to.

* id

  string

  A unique identifier for the element.

* initials

  string

  Initials to display in the avatar.

  Initials will be rendered as a fallback if `src` is not provided, fails to load or does not load quickly.

* size

  'small' | 'large' | 'base' | 'small-200' | 'large-200'

  Default: 'base'

  Size of the avatar.

* src

  string

  The URL or path to the image.

## Events

Learn more about [registering events](https://shopify.dev/docs/api/app-home/using-polaris-components#event-handling).

* error

  ((event: CallbackEventListener\<typeof tagName>) => void) | null

  Callback when the image fails to load.

* load

  ((event: CallbackEventListener\<typeof tagName>) => void) | null

  Callback when the image loads successfully.

### CallbackEventListener

```ts
(EventListener & {
      (event: CallbackEvent<TTagName, TEvent>): void;
    }) | null
```

### CallbackEvent

```ts
TEvent & {
  currentTarget: HTMLElementTagNameMap[TTagName];
}
```

### Examples

* #### Code

  ##### Default

  ```jsx
  <s-avatar
    alt="Avery Brown"
    initials="AB"
  ></s-avatar>
  ```

## Preview

![An example of the Avatar component shows the initials of the user.](https://shopify.dev/images/templated-apis-screenshots/customer-account-ui-extensions/2025-10/avatar-default.png)

## Best practices

Use these best practices to deliver a clear and accessible experience in your extensions.

### Show initials by default

When no first or last name is provided, display the placeholder icon. If either name exists, show one or two initials.

### Choose an appropriate size

Select a size based on context:

* small‑200 (21×21) for tight tables or lists
* small (26×26) when slightly larger is needed
* base (32×32) as the default
* large (39×39) when the avatar is a focal point (for example, a customer card)
* large‑200 (47×47) when extra emphasis is required

### Provide descriptive alt text

Write alt text that meaningfully describes the avatar so assistive technologies can convey the same context.

### Keep sizes consistent on a page

Use the same style and size for multiple avatars in one view to create a unified visual pattern and avoid mixing sizes.