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

Use s-thumbnail for product and content previews instead of carrying an Avatar forward only because it provides a compact image.

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

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

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

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris avatar component.

Anchor to sourcesource

Rename source to src. Both properties accept the URL of the avatar image and fall back when the image can't load.

Anchor to accessibilityLabel and nameaccessibilityLabel and name

Replace the accessible name supplied by accessibilityLabel or name with alt.

Anchor to initialsinitials

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.

Anchor to sizesize

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

Anchor to onErroronError

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.

Anchor to Removed propertiesRemoved properties

Anchor to namename

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.

Anchor to customercustomer

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.

Anchor to New events and behaviorNew events and behavior

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

Anchor to Test the migrationTest 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.

Anchor to Related guidanceRelated guidance

• Avatar component
• Avatar best practices
• Migrate from Polaris React