---
title: Avatar
description: >-
  The avatar component displays profile images or initials for users, customers,
  and businesses in a compact visual format. Use avatar to represent people or
  entities throughout the interface, with automatic fallback to initials when
  images aren't available.
api_version: 2026-04
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/avatar
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/avatar.md
---

# Avatar

The avatar component displays profile images or initials for users, customers, and businesses in a compact visual format. Use avatar to represent people or entities throughout the interface, with automatic fallback to initials when images aren't available.

Avatars support multiple sizes for different contexts and provide consistent color assignment for initials based on the name provided. For product preview images, use [product thumbnail](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/product-thumbnail). For full-size images, use [image](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/image).

Avatar images must be served from URLs accessible by the customer's browser, with proper `Access-Control-Allow-Origin` headers for cross-origin sources. Standard web image formats (JPEG, PNG, GIF, WebP, SVG) are supported — unsupported formats fall back to initials.

### Support Targets (24)

### Supported targets

* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-announcement-)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

#### Use cases

* **Customer identification**: Display customer avatars with initials or images in account pages.
* **User representation**: Show user profile images in order histories and account details.
* **Visual recognition**: Help customers quickly identify accounts and contacts with avatar imagery.
* **Compact displays**: Represent users in space-constrained interfaces like lists and cards.

***

## Properties

Configure the following properties on the avatar component.

* **alt**

  **string**

  Alternative text that describes the avatar for accessibility.

  Provides a text description of the avatar for users with assistive technology and serves as a fallback when the avatar fails to load. A well-written description enables people with visual impairments to understand non-text content.

  When a screen reader encounters an avatar, it reads this description aloud. When an avatar fails to load, this text displays on screen, helping all users understand what content was intended.

  Learn more about [writing effective alt text](https://www.shopify.com/ca/blog/image-alt-text#4) and the [alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt).

* **id**

  **string**

  A unique identifier for the element. Use this to target the element with CSS, JavaScript, or accessibility attributes. The `id` must be unique within the document.

* **initials**

  **string**

  The initials to display in the avatar when no image is provided or fails to load. Typically one or two characters representing a person's first and last name initials, such as "JD" for John Doe.

  Characters beyond the first two might be truncated. Special characters, emojis, and non-Latin scripts might not render as expected.

* **size**

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

  **Default: 'base'**

  The size of the avatar image.

  * `'small'`: Small avatar, good for secondary contexts or tight layouts.
  * `'large'`: Large avatar for emphasis or when the avatar is a focal point.
  * `'base'`: Default size that works well in most contexts.
  * `'small-200'`: Extra small avatar, suitable for compact displays or lists with many items.
  * `'large-200'`: Extra large avatar for prominent display.

* **src**

  **string**

  The URL or path to the avatar image. When provided, the image takes priority over `initials`. If the image fails to load or loads slowly, `initials` will be rendered as a fallback.

### Events

The avatar component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/polaris/using-polaris-web-components#handling-events).

* **error**

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

  A callback that's fired when the avatar image fails to load.

* **load**

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

  A callback that's fired when the avatar image has loaded successfully.

### CallbackEventListener

A typed event listener for custom element events. The listener receives a \`CallbackEvent\` with the correct \`currentTarget\` type for the associated custom element tag.

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

### CallbackEvent

An event type that narrows the \`currentTarget\` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.

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

***

## Examples

### Display initials

Identify customers visually when no profile image is available. This example displays an avatar with initials derived from a name.

## Display initials

![A circular avatar displaying initials derived from a customer name on a colored background.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/customer-account-ui-extensions/2025-10/avatar-default-DPPa0kQo.png)

## html

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

### Show a placeholder avatar

Represent unknown customers with a generic icon. This example displays a placeholder avatar when no initials or image are provided.

## html

```html
<s-avatar alt="Customer"></s-avatar>
```

### Load an image with fallback

Display profile photos with graceful error handling. This example presents an avatar with a source image that falls back to initials if the image fails to load.

## html

```html
<s-avatar
  src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
  initials="MR"
  alt="Maria Rodriguez"
  size="base"
></s-avatar>
```

### Adjust the size

Adapt avatar prominence to different UI contexts. This example demonstrates all five available sizes from `small-200` to `large-200`.

## html

```html
<s-stack direction="inline" gap="base">
  <s-avatar initials="SC" alt="Store customer" size="small-200"></s-avatar>
  <s-avatar initials="MR" alt="Maria Rodriguez" size="small"></s-avatar>
  <s-avatar initials="AB" alt="Avery Brown" size="base"></s-avatar>
  <s-avatar initials="JD" alt="Jordan Davis" size="large"></s-avatar>
  <s-avatar initials="TK" alt="Taylor Kim" size="large-200"></s-avatar>
</s-stack>
```

### Handle long names

Display initials of varying lengths consistently. This example presents avatars with two, three, and four character initials.

## html

```html
<s-stack direction="inline" gap="base">
  <s-avatar initials="AB" alt="Avery Brown" size="base"></s-avatar>
  <s-avatar initials="MRJ" alt="Maria Rodriguez Jr" size="base"></s-avatar>
  <s-avatar initials="SHOP" alt="Shopify customer" size="base"></s-avatar>
</s-stack>
```

### Maintain color consistency

Ensure visual consistency across the interface. This example demonstrates that avatars with identical initials always display the same background color.

## html

```html
<s-stack direction="inline" gap="base">
  <s-avatar initials="AB" alt="Avery Brown" size="base"></s-avatar>
  <s-avatar initials="CD" alt="Casey Davis" size="base"></s-avatar>
  <s-avatar initials="EF" alt="Emily Foster" size="base"></s-avatar>
  <s-avatar initials="AB" alt="Alex Bennett" size="base"></s-avatar>
</s-stack>
```

### Display in a customer list

Show customer identities in list views. This example pairs avatars with customer names in a vertical stack layout.

## html

```html
<s-stack gap="base">
  <s-stack direction="inline" gap="small">
    <s-avatar
      src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
      initials="AB"
      alt="Avery Brown"
      size="small"
    ></s-avatar>
    <s-text>Avery Brown</s-text>
  </s-stack>
  <s-stack direction="inline" gap="small">
    <s-avatar initials="MR" alt="Maria Rodriguez" size="small"></s-avatar>
    <s-text>Maria Rodriguez</s-text>
  </s-stack>
  <s-stack direction="inline" gap="small">
    <s-avatar
      src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
      initials="JD"
      alt="Jordan Davis"
      size="small"
    ></s-avatar>
    <s-text>Jordan Davis</s-text>
  </s-stack>
</s-stack>
```

### Build a customer profile card

Create a profile layout with multiple components. This example combines an avatar with [section](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/section), [heading](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/typography-and-content/heading), and [text](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/typography-and-content/text) components.

## html

```html
<s-section>
  <s-stack gap="base">
    <s-stack direction="inline" gap="small">
      <s-avatar
        src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
        initials="AB"
        alt="Avery Brown"
        size="base"
      ></s-avatar>
      <s-stack gap="small-400">
        <s-heading>Avery Brown</s-heading>
        <s-text color="subdued">Member since 2023</s-text>
      </s-stack>
    </s-stack>
    <s-text>Loyalty tier: Gold</s-text>
  </s-stack>
</s-section>
```

***

## Best practices

* **Choose appropriate sizes**: Use smaller sizes for compact contexts like tables and lists, and larger sizes for profile pages where the person is the primary focus.
* **Provide meaningful alt text**: Describe the avatar content like "Sarah Chen" or "Acme Corporation", or use empty alt text if the name appears next to the avatar as text.
* **Position near related content**: Place avatars adjacent to the names or entities they represent for clear associations in lists, tables, or cards.
* **Show initials by default**: When no profile image is available, display initials derived from the customer's name. If no name is provided, display the placeholder icon.
* **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.

***