---
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-04
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-04/components/avatar
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-04/components/avatar.md
---

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

## AvatarProps

* alt

  string

  An alternative text description that describe the image for the reader to understand what it is about or identify the user the avatar belongs to.

* id

  string

  A unique identifier for the component.

* initials

  string

  Initials to display in the avatar.

* onError

  () => void

  Invoked on load error of provided image.

* onLoad

  () => void

  Invoked when load of provided image completes successfully.

* size

  Extract\<Size, 'base' | 'large' | 'extraLarge' | 'fill'>

  Default: 'base'

  Size of the avatar.

* src

  string

  The URL or path to the image.

  Initials will be rendered as a fallback if `src` is not provided, fails to load or does not load quickly.

### Size

```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://shopify.dev/images/templated-apis-screenshots/customer-account-ui-extensions/2025-04/avatar-preview.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',
    () => <App />,
  );

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

  ##### 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://shopify.dev/images/templated-apis-screenshots/customer-account-ui-extensions/unstable/avatar-best-practices.png)