Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

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 ProductThumbnail. For full-size images, use Image.

Support

Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the Avatar component.

Anchor to alt alt string: The alternative text that describes the avatar for assistive technologies. Screen readers announce this text when they encounter the avatar, and it displays as a fallback if the image fails to load.

Learn more about writing effective alternative text.
Anchor to id id string: A unique identifier for the component.
Anchor to initials initials string: The initials to display in the avatar. Used as a text fallback when no image is available or while the image is loading.
Anchor to onError onError () => void: A callback that fires when the avatar image fails to load (for example, due to a broken URL or network error). Use this to show a fallback or error state.
Anchor to onLoad onLoad () => void: A callback that fires when the avatar image finishes loading successfully. Use this to trigger UI updates that depend on the image being ready (for example, removing a loading skeleton).
Anchor to size size Default: 'base': The size of the avatar.
Anchor to src src string: The URL or path to the avatar image. Supports remote URLs and local file resources. Initials are rendered as a fallback if src is not provided, fails to load, or does not load quickly.

Anchor to ExamplesExamples

Anchor to Display initialsDisplay initials

Identify customers visually when no profile image is available. This example displays avatars with initials derived from customer names.

Display initials

import {

Avatar,

InlineStack,

reactExtension,

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

import React from 'react';

export default reactExtension(

'customer-account.page.render',

() => <App />,

);

function App() {

return (

</InlineStack>

);

}

import {

Avatar,

InlineStack,

extension,

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

export default extension('customer-account.page.render', (root, api) => {

renderApp(root, api);

});

async function renderApp(root, api) {

const avatar = root.createComponent(Avatar, {

alt: 'John Doe',

});

const avatarWithInitials = root.createComponent(Avatar, {

initials: 'EW',

alt: 'Evan Williams',

});

const inlineStack = root.createComponent(InlineStack, {spacing: 'large500'});

inlineStack.append(avatar);

inlineStack.append(avatarWithInitials);

root.append(inlineStack);

}

React

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

export default reactExtension(
  'customer-account.page.render',
  () => <App />,
);

function App() {
  return (
    <InlineStack spacing="large500">
      <Avatar alt="John Doe" />
      <Avatar initials="EW" alt="Evan Williams" />
    </InlineStack>
  );
}

JS

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

export default extension('customer-account.page.render', (root, api) => {
  renderApp(root, api);
});

async function renderApp(root, api) {
  const avatar = root.createComponent(Avatar, {
    alt: 'John Doe',
  });

  const avatarWithInitials = root.createComponent(Avatar, {
    initials: 'EW',
    alt: 'Evan Williams',
  });

  const inlineStack = root.createComponent(InlineStack, {spacing: 'large500'});
  inlineStack.append(avatar);
  inlineStack.append(avatarWithInitials);

  root.append(inlineStack);
}

Anchor to Load an image avatarLoad an image avatar

Display an avatar with a profile image that falls back to initials if the image fails to load. This example shows the avatar alongside the customer's name and membership details.

Load an image avatar

import {

reactExtension,

Avatar,

Text,

InlineStack,

BlockStack,

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

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

<Avatar

src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"

initials="MR"

alt="Maria Rodriguez"

<Text emphasis="bold">Maria Rodriguez</Text>

<Text appearance="subdued">Member since 2023</Text>

</BlockStack>

</InlineStack>

);

}

import {extension, Avatar, Text, InlineStack, BlockStack} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {

const avatar = root.createComponent(Avatar, {

src: 'https://cdn.shopify.com/static/sample-product/House-Plant1.png',

initials: 'MR',

alt: 'Maria Rodriguez',

});

const name = root.createComponent(Text, {emphasis: 'bold'}, 'Maria Rodriguez');

const member = root.createComponent(Text, {appearance: 'subdued'}, 'Member since 2023');

const details = root.createComponent(BlockStack, {spacing: 'extraTight'});

details.append(name);

details.append(member);

const row = root.createComponent(InlineStack, {spacing: 'base'});

row.append(avatar);

row.append(details);

root.append(row);

});

React

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

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

function Extension() {
  return (
    <InlineStack spacing="base">
      <Avatar
        src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
        initials="MR"
        alt="Maria Rodriguez"
      />
      <BlockStack spacing="extraTight">
        <Text emphasis="bold">Maria Rodriguez</Text>
        <Text appearance="subdued">Member since 2023</Text>
      </BlockStack>
    </InlineStack>
  );
}

JS

import {extension, Avatar, Text, InlineStack, BlockStack} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
  const avatar = root.createComponent(Avatar, {
    src: 'https://cdn.shopify.com/static/sample-product/House-Plant1.png',
    initials: 'MR',
    alt: 'Maria Rodriguez',
  });

  const name = root.createComponent(Text, {emphasis: 'bold'}, 'Maria Rodriguez');
  const member = root.createComponent(Text, {appearance: 'subdued'}, 'Member since 2023');
  const details = root.createComponent(BlockStack, {spacing: 'extraTight'});
  details.append(name);
  details.append(member);

  const row = root.createComponent(InlineStack, {spacing: 'base'});
  row.append(avatar);
  row.append(details);

  root.append(row);
});

Anchor to Display in a customer listDisplay in a customer list

Render a list of customers with initials-based avatars. This example shows multiple avatars at a consistent size alongside customer names for a compact list view.

Display in a customer list

import {

reactExtension,

Avatar,

Text,

InlineStack,

BlockStack,

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

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

<Text>Avery Brown</Text>

</InlineStack>

<Text>Maria Rodriguez</Text>

</InlineStack>

<Text>Jordan Davis</Text>

</InlineStack>

</BlockStack>

);

}

import {extension, Avatar, Text, InlineStack, BlockStack} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {

function createRow(initials, name) {

const avatar = root.createComponent(Avatar, {initials, alt: name});

const text = root.createComponent(Text, {}, name);

const row = root.createComponent(InlineStack, {spacing: 'small'});

row.append(avatar);

row.append(text);

return row;

}

const stack = root.createComponent(BlockStack, {spacing: 'base'});

stack.append(createRow('AB', 'Avery Brown'));

stack.append(createRow('MR', 'Maria Rodriguez'));

stack.append(createRow('JD', 'Jordan Davis'));

root.append(stack);

});

React

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

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

function Extension() {
  return (
    <BlockStack spacing="base">
      <InlineStack spacing="small">
        <Avatar initials="AB" alt="Avery Brown" />
        <Text>Avery Brown</Text>
      </InlineStack>
      <InlineStack spacing="small">
        <Avatar initials="MR" alt="Maria Rodriguez" />
        <Text>Maria Rodriguez</Text>
      </InlineStack>
      <InlineStack spacing="small">
        <Avatar initials="JD" alt="Jordan Davis" />
        <Text>Jordan Davis</Text>
      </InlineStack>
    </BlockStack>
  );
}

JS

import {extension, Avatar, Text, InlineStack, BlockStack} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
  function createRow(initials, name) {
    const avatar = root.createComponent(Avatar, {initials, alt: name});
    const text = root.createComponent(Text, {}, name);
    const row = root.createComponent(InlineStack, {spacing: 'small'});
    row.append(avatar);
    row.append(text);
    return row;
  }

  const stack = root.createComponent(BlockStack, {spacing: 'base'});
  stack.append(createRow('AB', 'Avery Brown'));
  stack.append(createRow('MR', 'Maria Rodriguez'));
  stack.append(createRow('JD', 'Jordan Davis'));

  root.append(stack);
});

Anchor to Show a placeholder avatarShow a placeholder avatar

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

Show a placeholder avatar

import {

reactExtension,

Avatar,

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

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return <Avatar alt="Unknown customer" />;

}

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

export default extension('customer-account.page.render', (root) => {

const avatar = root.createComponent(Avatar, {alt: 'Unknown customer'});

root.append(avatar);

});

React

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

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

function Extension() {
  return <Avatar alt="Unknown customer" />;
}

JS

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

export default extension('customer-account.page.render', (root) => {
  const avatar = root.createComponent(Avatar, {alt: 'Unknown customer'});
  root.append(avatar);
});

Anchor to Adjust the sizeAdjust the size

Adapt avatar prominence to different UI contexts. This example demonstrates base, large, and extraLarge sizes aligned along the bottom edge.

Adjust the size

import {

reactExtension,

Avatar,

InlineStack,

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

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

</InlineStack>

);

}

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

export default extension('customer-account.page.render', (root) => {

const row = root.createComponent(InlineStack, {spacing: 'base', blockAlignment: 'end'});

['base', 'large', 'extraLarge'].forEach((size) => {

row.append(root.createComponent(Avatar, {initials: 'AB', alt: 'Avery Brown', size}));

});

root.append(row);

});

React

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

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

function Extension() {
  return (
    <InlineStack spacing="base" blockAlignment="end">
      <Avatar initials="AB" alt="Avery Brown" size="base" />
      <Avatar initials="AB" alt="Avery Brown" size="large" />
      <Avatar initials="AB" alt="Avery Brown" size="extraLarge" />
    </InlineStack>
  );
}

JS

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

export default extension('customer-account.page.render', (root) => {
  const row = root.createComponent(InlineStack, {spacing: 'base', blockAlignment: 'end'});

  ['base', 'large', 'extraLarge'].forEach((size) => {
    row.append(root.createComponent(Avatar, {initials: 'AB', alt: 'Avery Brown', size}));
  });

  root.append(row);
});

Anchor to Best practicesBest practices

Choose appropriate sizes: Use the default base size for compact contexts like 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.
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.

Anchor to LimitationsLimitations

Avatar images must be served from URLs accessible by the customer's browser. Cross-origin images require appropriate Access-Control-Allow-Origin headers or the image might fail to load.
Only standard web image formats (JPEG, PNG, GIF, WebP, SVG) are supported. Unsupported formats fall back to initials.
Characters beyond the first two in initials might be truncated.

Was this page helpful?