---
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: 2026-01
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

## Preview

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

### Examples

* #### Code

  ##### Default

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

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