--- title: Avatar description: >- Avatar component is used to show a thumbnail representation of an individual or business in the interface. It can be a graphical representation or visual depiction, such as an image, initials, or an icon. 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/api/customer-account-ui-extensions/2025-10/upgrading-to-2025-10) to upgrade your extension. # Avatar Avatar component is used to show a thumbnail representation of an individual or business in the interface. It can be a graphical representation or visual depiction, such as an image, initials, or an icon. ### Support Targets (25) ### Supported targets * Customer​Account::Kitchen​Sink * customer-account.​footer.​render-after * customer-account.​order-index.​announcement.​render * customer-account.​order-index.​block.​render * customer-account.​order-status.​announcement.​render * customer-account.​order-status.​block.​render * customer-account.​order-status.​cart-line-item.​render-after * customer-account.​order-status.​cart-line-list.​render-after * customer-account.​order-status.​customer-information.​render-after * customer-account.​order-status.​fulfillment-details.​render-after * customer-account.​order-status.​payment-details.​render-after * customer-account.​order-status.​return-details.​render-after * customer-account.​order-status.​unfulfilled-items.​render-after * customer-account.​order.​action.​menu-item.​render * customer-account.​order.​action.​render * customer-account.​order.​page.​render * customer-account.​page.​render * customer-account.​profile.​addresses.​render-after * customer-account.​profile.​announcement.​render * customer-account.​profile.​block.​render * customer-account.​profile.​company-details.​render-after * customer-account.​profile.​company-location-addresses.​render-after * customer-account.​profile.​company-location-payment.​render-after * customer-account.​profile.​company-location-staff.​render-after * customer-account.​profile.​payment.​render-after ## AvatarProps * **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** **Extract\** **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. ### Size A keyword that maps to a predefined size from the design system's size scale. Components use a subset of these values depending on which sizes they support. - \`extraSmall\`: The smallest available size. - \`small\`: A compact size, smaller than the default. - \`base\`: The default size, appropriate for most contexts. - \`large\`: A larger size for increased visual prominence. - \`extraLarge\`: The largest available keyword size. - \`fill\`: Stretches to fill the available space in the container. ```ts 'extraSmall' | 'small' | 'base' | 'large' | 'extraLarge' | 'fill' ``` Examples ## Preview ![An example of the avatar with two variants: one with initials and the other with an icon.](https://cdn.shopify.com/shopifycloud/shopify-dev/development/assets/assets/images/templated-apis-screenshots/customer-account-ui-extensions/2025-07/avatar-preview--obY5fMR.png) ### Examples * #### Basic Avatar ##### 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); } ``` ## Best Practices * By default, if a user does not provide their first or last name, the avatar component will display a placeholder icon. However, if at least one of the names is provided, the avatar will be replaced with one or two initials representing the user. * There are 4 sizes for the avatar component: * Base (32x32 px): Use by default. * Large (39×39 px): Use when the avatar is a focal point, such as a customer details card. * Extra-large (47x47 px): Use when placing more emphasis on the avatar * Fill to fit: Use when there is a particular size that does not match any of the three sizes provided. If using images please ensure the resolution meets the size requirements. * Provide alt text for avatars to assist customers using assistive technologies. **Dos** * When using multiple avatars on the same page, maintain a consistent style and size to create a unified visual pattern for users. **Don'ts** * Don't use different size avatars on the same page. ![An example showing dos and don'ts of the Avatar component](https://cdn.shopify.com/shopifycloud/shopify-dev/development/assets/assets/images/templated-apis-screenshots/customer-account-ui-extensions/2025-07/avatar-best-practices-Cnupij88.png)