Migrate Avatar to the Polaris avatar component

The Polaris avatar component shows a thumbnail representation of an individual or business. It replaces the previous Avatar component and is available as <s-avatar> in API versions 2025-10 and newer.

Migrating Avatar to s-avatar

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

return (

<s-avatar

src="https://example.com/customer.jpg"

alt="Alex Doe"

initials="AD"

size="large"

></s-avatar>

);

}

import {

Avatar,

reactExtension,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.profile.block.render',

() => <Extension />,

);

function Extension() {

return (

<Avatar

src="https://example.com/customer.jpg"

alt="Alex Doe"

initials="AD"

size="large"

);

}

Latest (Preact)

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-avatar
      src="https://example.com/customer.jpg"
      alt="Alex Doe"
      initials="AD"
      size="large"
    ></s-avatar>
  );
}

Pre-Polaris (2025-07)

import {
  Avatar,
  reactExtension,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.profile.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Avatar
      src="https://example.com/customer.jpg"
      alt="Alex Doe"
      initials="AD"
      size="large"
    />
  );
}

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris avatar component.

Anchor to sizesize

The size prop values have changed.

Previous value	New value	Migration notes
`'base'`	`'base'`	No change needed. `'base'` is the default.
`'large'`	`'large'`	No change needed.
`'extraLarge'`	`'large-200'`	Renamed.
`'fill'`	Removed	The avatar no longer stretches to its container. Pick a fixed `size` value from the list above.

The Polaris avatar component also supports new smaller size values:

New value	Description
`'small'`	One step smaller than `'base'`.
`'small-200'`	Two steps smaller than `'base'`.

Migrating size values

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

return (

<s-avatar

src="https://example.com/customer.jpg"

alt="Alex Doe"

size="large-200"

></s-avatar>

);

}

import {

Avatar,

reactExtension,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.profile.block.render',

() => <Extension />,

);

function Extension() {

return (

<Avatar

src="https://example.com/customer.jpg"

alt="Alex Doe"

size="extraLarge"

);

}

Latest (Preact)

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-avatar
      src="https://example.com/customer.jpg"
      alt="Alex Doe"
      size="large-200"
    ></s-avatar>
  );
}

Pre-Polaris (2025-07)

import {
  Avatar,
  reactExtension,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.profile.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Avatar
      src="https://example.com/customer.jpg"
      alt="Alex Doe"
      size="extraLarge"
    />
  );
}

Was this page helpful?