---
title: Migrate Avatar from Polaris React
description: >-
  Learn how to migrate the Polaris React Avatar component to Polaris web
  components in an embedded app.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/avatar
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/avatar.md
api_name: app-home
---

# Migrate Avatar from Polaris React

The Polaris avatar component represents a person, customer, or business with an image, initials, or a generic placeholder. It replaces the Polaris React `Avatar` component from `@shopify/polaris` and is available as [`<s-avatar>`](https://shopify.dev/docs/api/app-home/web-components/media-and-visuals/avatar).

Use [`s-thumbnail`](https://shopify.dev/docs/api/app-home/web-components/media-and-visuals/thumbnail) for product and content previews instead of carrying an `Avatar` forward only because it provides a compact image.

## Migrating Avatar to s-avatar

##### Polaris web components

```tsx
export function CustomerAvatar() {
  return (
    <s-avatar
      alt="Maria Rodriguez"
      initials="MR"
      size="large-200"
    ></s-avatar>
  );
}
```

##### Polaris React

```tsx
import {Avatar} from '@shopify/polaris';

export function CustomerAvatar() {
  return (
    <Avatar name="Maria Rodriguez" initials="MR" size="xl" />
  );
}
```

***

## Updated properties

The following properties are different in the Polaris avatar component.

### source

Rename `source` to [`src`](https://shopify.dev/docs/api/app-home/web-components/media-and-visuals/avatar#avatar-propertydetail-src). Both properties accept the URL of the avatar image and fall back when the image can't load.

| Polaris React | Polaris web components |
| - | - |
| `source={customer.imageUrl}` | `src={customer.imageUrl}` |

### accessibility​Label and name

Replace the accessible name supplied by `accessibilityLabel` or `name` with [`alt`](https://shopify.dev/docs/api/app-home/web-components/media-and-visuals/avatar#avatar-propertydetail-alt).

| Polaris React state | Polaris web components | Migration notes |
| - | - | - |
| `accessibilityLabel` is set | Set `alt` to the same text. | `accessibilityLabel` took precedence over `name`. |
| Only `name` is set | Set `alt` to `name`. | Polaris React used `name` as the accessible label; it didn't derive initials from it. |
| Only `initials` is set | Add an `alt` value that identifies the person or business. | Don't use spaced initials as the complete description. |
| The same name is visible beside the avatar | Consider `alt=""`. | An empty value avoids announcing the adjacent name twice. Test the complete row with a screen reader. |

### initials

The `initials` property has the same name and remains the fallback when no `src` is provided or the image fails to load. Use one or two characters. Polaris web components might truncate additional characters, so shorten existing values longer than two characters and verify names that don't use Latin characters.

Don't expect `alt` to generate `initials`; calculate the initials in app code when you want a monogram.

### size

Replace the abbreviated `size` values with the Polaris web component scale. These mappings preserve the corresponding avatar size.

| Polaris React value | Polaris web components |
| - | - |
| `"xs"` | `"small-200"` |
| `"sm"` | `"small"` |
| `"md"` or omitted | `"base"` or omitted |
| `"lg"` | `"large"` |
| `"xl"` | `"large-200"` |

### on​Error

`s-avatar` emits an `error` event when its image fails to load. In React, an existing no-argument handler can remain `onError={handleImageError}`. The component automatically displays `initials`, or the generic placeholder when no initials are provided, so don't add app state only to implement that fallback.

***

## Removed properties

### name

`s-avatar` doesn't have a `name` property. Move the old accessible-name behavior to `alt`. If the app used `name` to keep fallback colors consistent, supply a stable `alt` value; the Polaris web component derives its fallback color from `alt` or `initials`.

Polaris React didn't derive a monogram from `name`, and `s-avatar` doesn't either. Continue passing `initials` explicitly when you need them.

### customer

`s-avatar` doesn't have a `customer` property. Polaris React used `customer` to show the generic person placeholder even when `initials` were provided.

To preserve `customer={true}` fallback behavior, migrate the accessible name to `alt` and omit `initials`. If you want the customer's initials instead, pass them explicitly. In both cases, `src` still takes priority when the image loads.

***

## New events and behavior

The Polaris avatar component adds or makes the following behavior explicit:

| Event or behavior | Description |
| - | - |
| `load` event | Runs after the avatar image loads successfully. Use `onLoad` in React only when app logic needs the result. |
| Automatic fallback order | Renders `src` first, then `initials`, then a generic placeholder. |
| Stable fallback color | Derives the initials background from `alt` or `initials`; no separate color property is needed. |

***

## Test the migration

* Test the loaded image, failed image, initials, and generic-placeholder states used by the app.
* Confirm each avatar has useful alternative text, or an empty `alt` when adjacent text already identifies it.
* Compare every old size in the actual table, list, or profile layout where it appears.
* Verify `customer={true}` call sites don't unexpectedly reveal initials after migration.
* Confirm image error handling still runs and that the fallback appears without app-managed loading state.
* Remove the Polaris React `Avatar` import after its final consumer is migrated.

***

## Related guidance

* [Avatar component](https://shopify.dev/docs/api/app-home/web-components/media-and-visuals/avatar)
* [Avatar best practices](https://shopify.dev/docs/api/app-home/web-components/media-and-visuals/avatar#best-practices)
* [Migrate from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react)

***