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 product thumbnail. For full-size images, use image.

Avatar images must be served from URLs accessible by the customer's browser, with proper Access-Control-Allow-Origin headers for cross-origin sources. Standard web image formats (JPEG, PNG, GIF, WebP, SVG) are supported — unsupported formats fall back to initials.

Support

Targets (24)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the avatar component.

Anchor to alt alt string: Alternative text that describes the avatar for accessibility.

Provides a text description of the avatar for users with assistive technology and serves as a fallback when the avatar fails to load. A well-written description enables people with visual impairments to understand non-text content.

When a screen reader encounters an avatar, it reads this description aloud. When an avatar fails to load, this text displays on screen, helping all users understand what content was intended.

Learn more about writing effective alt text and the alt attribute.
Anchor to id id string: A unique identifier for the element. Use this to target the element with CSS, JavaScript, or accessibility attributes. The id must be unique within the document.
Anchor to initials initials string: The initials to display in the avatar when no image is provided or fails to load. Typically one or two characters representing a person's first and last name initials, such as "JD" for John Doe.

Characters beyond the first two might be truncated. Special characters, emojis, and non-Latin scripts might not render as expected.
Anchor to size size 'small' | 'large' | 'base' | 'small-200' | 'large-200' Default: 'base': The size of the avatar image.

'small': Small avatar, good for secondary contexts or tight layouts.

'large': Large avatar for emphasis or when the avatar is a focal point.

'base': Default size that works well in most contexts.

'small-200': Extra small avatar, suitable for compact displays or lists with many items.

'large-200': Extra large avatar for prominent display.
Anchor to src src string: The URL or path to the avatar image. When provided, the image takes priority over initials. If the image fails to load or loads slowly, initials will be rendered as a fallback.

Anchor to EventsEvents

The avatar component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to error error ((event: <typeof tagName>) => void) | null: A callback that's fired when the avatar image fails to load.
Anchor to load load ((event: <typeof tagName>) => void) | null: A callback that's fired when the avatar image has loaded successfully.

CallbackEventListener

A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.

(EventListener & {
      (event: CallbackEvent<TTagName, TEvent>): void;
    }) | null

CallbackEvent

An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.

TEvent & {
  currentTarget: HTMLElementTagNameMap[TTagName];
}

Anchor to ExamplesExamples

Anchor to Display initialsDisplay initials

Identify customers visually when no profile image is available. This example displays an avatar with initials derived from a name.

Display initials

html

<s-avatar alt="Avery Brown" initials="AB"></s-avatar>

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.

html

<s-avatar alt="Customer"></s-avatar>

Anchor to Load an image with fallbackLoad an image with fallback

Display profile photos with graceful error handling. This example presents an avatar with a source image that falls back to initials if the image fails to load.

html

<s-avatar

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

initials="MR"

alt="Maria Rodriguez"

size="base"

></s-avatar>

Anchor to Adjust the sizeAdjust the size

Adapt avatar prominence to different UI contexts. This example demonstrates all five available sizes from small-200 to large-200.

html

<s-stack direction="inline" gap="base">

<s-avatar initials="SC" alt="Store customer" size="small-200"></s-avatar>

<s-avatar initials="MR" alt="Maria Rodriguez" size="small"></s-avatar>

<s-avatar initials="AB" alt="Avery Brown" size="base"></s-avatar>

<s-avatar initials="JD" alt="Jordan Davis" size="large"></s-avatar>

<s-avatar initials="TK" alt="Taylor Kim" size="large-200"></s-avatar>

</s-stack>

Anchor to Handle long namesHandle long names

Display initials of varying lengths consistently. This example presents avatars with two, three, and four character initials.

html

<s-stack direction="inline" gap="base">

<s-avatar initials="AB" alt="Avery Brown" size="base"></s-avatar>

<s-avatar initials="MRJ" alt="Maria Rodriguez Jr" size="base"></s-avatar>

<s-avatar initials="SHOP" alt="Shopify customer" size="base"></s-avatar>

</s-stack>

Anchor to Maintain color consistencyMaintain color consistency

Ensure visual consistency across the interface. This example demonstrates that avatars with identical initials always display the same background color.

html

<s-stack direction="inline" gap="base">

<s-avatar initials="AB" alt="Avery Brown" size="base"></s-avatar>

<s-avatar initials="CD" alt="Casey Davis" size="base"></s-avatar>

<s-avatar initials="EF" alt="Emily Foster" size="base"></s-avatar>

<s-avatar initials="AB" alt="Alex Bennett" size="base"></s-avatar>

</s-stack>

Anchor to Display in a customer listDisplay in a customer list

Show customer identities in list views. This example pairs avatars with customer names in a vertical stack layout.

html

<s-stack gap="base">

<s-stack direction="inline" gap="small">

<s-avatar

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

initials="AB"

alt="Avery Brown"

size="small"

></s-avatar>

<s-text>Avery Brown</s-text>

</s-stack>

<s-stack direction="inline" gap="small">

<s-avatar initials="MR" alt="Maria Rodriguez" size="small"></s-avatar>

<s-text>Maria Rodriguez</s-text>

</s-stack>

<s-stack direction="inline" gap="small">

<s-avatar

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

initials="JD"

alt="Jordan Davis"

size="small"

></s-avatar>

<s-text>Jordan Davis</s-text>

</s-stack>

Anchor to Build a customer profile cardBuild a customer profile card

Create a profile layout with multiple components. This example combines an avatar with section, heading, and text components.

html

<s-section>

<s-stack gap="base">

<s-stack direction="inline" gap="small">

<s-avatar

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

initials="AB"

alt="Avery Brown"

size="base"

></s-avatar>

<s-stack gap="small-400">

<s-heading>Avery Brown</s-heading>

<s-text color="subdued">Member since 2023</s-text>

</s-stack>

<s-text>Loyalty tier: Gold</s-text>

</s-stack>

</s-section>

Anchor to Best practicesBest practices

Choose appropriate sizes: Use smaller sizes for compact contexts like tables and 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.
Position near related content: Place avatars adjacent to the names or entities they represent for clear associations in lists, tables, or cards.
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.

Was this page helpful?