---
title: Image
description: >-
  The image component embeds images within the interface with control over
  presentation and loading behavior. Use image to visually illustrate concepts,
  showcase products, display user content, or support tasks and interactions
  with visual context.
api_name: app-home
source_url:
  html: 'https://shopify.dev/docs/api/app-home/web-components/media-and-visuals/image'
  md: >-
    https://shopify.dev/docs/api/app-home/web-components/media-and-visuals/image.md
---

# Image

The image component embeds images within the interface with control over presentation and loading behavior. Use image to visually illustrate concepts, showcase products, display user content, or support tasks and interactions with visual context.

Images support responsive sizing, alt text for accessibility, aspect ratio control, and loading states for progressive enhancement. For small preview images in lists or tables, use [thumbnail](https://shopify.dev/docs/api/app-home//polaris-web-components/media-and-visuals/thumbnail). For profile images, use [avatar](https://shopify.dev/docs/api/app-home//polaris-web-components/media-and-visuals/avatar).

#### Use cases

* **Product visuals:** Display product images in configuration interfaces or recommendations.
* **Branding:** Show app logos or brand imagery in action modals.
* **Visual guides:** Provide visual instructions or examples for complex configurations.
* **Marketing content:** Display promotional banners or feature announcements.

***

## Properties

* **id**

  **string**

  **required**

* **originalSrc**

  **string**

  **required**

* **altText**

  **string**

### Events

The image component provides event callbacks for handling user interactions. Learn more about [handling events](https://shopify.dev/docs/api/polaris/using-polaris-web-components#handling-events).

* **error**

  **OnErrorEventHandler**

  **required**

  A callback fired when the image fails to load.

  Learn more about the [error event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/error_event).

* **load**

  **CallbackEventListener\<typeof tagName> | null**

  **required**

  A callback fired when the image successfully loads.

  Learn more about the [load event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/load_event).

### CallbackEventListener

A function that handles events from UI components. This type represents an event listener callback that receives a \`CallbackEvent\` with a strongly-typed \`currentTarget\`. Use this for component event handlers like \`click\`, \`focus\`, \`blur\`, and other DOM events.

```ts
(EventListener & {
      (event: CallbackEvent<T>): void;
    }) | null
```

### CallbackEvent

An event object with a strongly-typed \`currentTarget\` property that references the specific HTML element that triggered the event. This type extends the standard DOM \`Event\` interface and ensures type safety when accessing the element that fired the event.

```ts
Event & {
  currentTarget: HTMLElementTagNameMap[T];
}
```

***

## Examples

### Display a product thumbnail

Display a product thumbnail with metadata in a grid layout. This example demonstrates how to control image sizing with `aspectRatio`, `objectFit`, and `inlineSize`, and round corners with `borderRadius`.

## html

```html
<s-grid gridTemplateColumns="80px 1fr" gap="base" alignItems="center">
  <s-image
    src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
    alt="Indoor plant"
    aspectRatio="1/1"
    objectFit="cover"
    borderRadius="base"
    inlineSize="fill"
  />
  <s-stack gap="small">
    <s-text type="strong">Indoor Plant</s-text>
    <s-text color="subdued">SKU: PLT-001</s-text>
    <s-text tone="success">In stock</s-text>
  </s-stack>
</s-grid>
```

### Set an aspect ratio

Control image proportions with a fixed aspect ratio. This example displays a 16:9 image that scales to fill its container using `objectFit="cover"`, with lazy loading for performance.

## html

```html
<s-image
  src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
  alt="Featured product"
  aspectRatio="16/9"
  objectFit="cover"
  loading="lazy"
></s-image>
```

### Use responsive images

Set up responsive image sources using `srcSet` and `sizes`. This example demonstrates how to configure the browser to select appropriate image sources based on viewport width.

## html

```html
<s-image
  src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
  srcSet="https://cdn.shopify.com/static/sample-product/House-Plant1.png 400w,
          https://cdn.shopify.com/static/sample-product/House-Plant1.png 800w"
  sizes="(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 400px"
  alt="Product detail"
  aspectRatio="16/9"
  objectFit="cover"
></s-image>
```

### Add border styling

Add visual emphasis with border styling. This example displays an image with border width, color, and rounded corners.

## html

```html
<s-box inlineSize="300px">
  <s-image
    src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
    alt="Product thumbnail"
    borderWidth="large"
    borderStyle="solid"
    borderColor="strong"
    borderRadius="large"
    objectFit="cover"
    aspectRatio="1/1"
  ></s-image>
</s-box>
```

### Mark as decorative

Hide images from screen readers when purely decorative. This example presents an image with empty `alt` text and `presentation` role for accessibility.

## html

```html
<s-image
  src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
  alt=""
  accessibilityRole="presentation"
  objectFit="cover"
></s-image>
```

### Use in a grid layout

Build a product image gallery with consistent sizing using [grid](https://shopify.dev/docs/api/app-home//web-components/layout-and-structure/grid). This example arranges three product photos in a row, each constrained to a square with rounded corners so they line up evenly.

## html

```html
<s-grid gridTemplateColumns="repeat(3, 150px)" gap="base" alignItems="center">
  <s-image
    src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
    alt="Main view"
    aspectRatio="1/1"
    objectFit="cover"
    borderRadius="base"
    inlineSize="fill"
  ></s-image>
  <s-image
    src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
    alt="Side view"
    aspectRatio="1/1"
    objectFit="cover"
    borderRadius="base"
    inlineSize="fill"
  ></s-image>
  <s-image
    src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
    alt="Detail view"
    aspectRatio="1/1"
    objectFit="cover"
    borderRadius="base"
    inlineSize="fill"
  ></s-image>
</s-grid>
```

***

## Useful for

* Adding illustrations and photos.

***

## Best practices

* Use high-resolution, optimized images.
* Use intentionally to add clarity and guide users.

***

## Content guidelines

Alt text should be accurate, concise, and descriptive:

* Indicate it's an image: "Image of", "Photo of".
* Focus on description: "Image of a woman with curly brown hair smiling".

***