--- 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: 2025-07 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/media-and-visuals/avatar md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/media-and-visuals/avatar.md --- Migrate to Polaris Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension. # 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](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/media-and-visuals/productthumbnail). For full-size images, use [Image](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/media-and-visuals/image). ### Support Targets (25) ### Supported targets * Customer​Account::Kitchen​Sink * [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-) * [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets) * [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-) * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-) * [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-) * [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-) * [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-) * [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-) * [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-) * [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/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/2025-07/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** 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](https://ux.shopify.com/considerations-when-writing-alt-text-a9c1985a8204). * **id** **string** A unique identifier for the component. * **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. * **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. * **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). * **size** **Default: 'base'** The size of the avatar. * **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. *** ## Examples ### Display initials Identify customers visually when no profile image is available. This example displays avatars with initials derived from customer names. ## Display initials ![Two avatars: one with a placeholder icon and the other with initials EW.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/customer-account-ui-extensions/2025-07/avatar-preview--obY5fMR.png) ## Display initials ##### React ```tsx import { Avatar, InlineStack, reactExtension, } from '@shopify/ui-extensions-react/customer-account'; import React from 'react'; export default reactExtension( 'customer-account.page.render', () => , ); function App() { return ( ); } ``` ##### JS ```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); } ``` ### Load 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 ##### React ```tsx import { reactExtension, Avatar, Text, InlineStack, BlockStack, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ( Maria Rodriguez Member since 2023 ); } ``` ##### JS ```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); }); ``` ### Display 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 ##### React ```tsx import { reactExtension, Avatar, Text, InlineStack, BlockStack, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ( Avery Brown Maria Rodriguez Jordan Davis ); } ``` ##### JS ```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); }); ``` ### Show 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 ##### React ```tsx import { reactExtension, Avatar, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ; } ``` ##### JS ```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); }); ``` ### Adjust 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 ##### React ```tsx import { reactExtension, Avatar, InlineStack, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ( ); } ``` ##### JS ```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); }); ``` *** ## Best 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. *** ## Limitations * 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. ***