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. For profile images, use avatar.

Anchor to PropertiesProperties

Anchor to id id string required
Anchor to originalSrc originalSrc string required
Anchor to altText altText string

Anchor to EventsEvents

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

Anchor to error error OnErrorEventHandler required: A callback fired when the image fails to load.

Learn more about the error event.
Anchor to load load <typeof tagName> | null required: A callback fired when the image successfully loads.

Learn more about the 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.

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

Event & {
  currentTarget: HTMLElementTagNameMap[T];
}

Anchor to ExamplesExamples

Anchor to Display a product thumbnailDisplay 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.

Preview

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>

Anchor to Set an aspect ratioSet 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.

Preview

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>

Anchor to Use responsive imagesUse 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.

Preview

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>

Anchor to Add border stylingAdd border styling

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

Preview

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>

Anchor to Mark as decorativeMark as decorative

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

Preview

html

<s-image

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

alt=""

accessibilityRole="presentation"

objectFit="cover"

></s-image>

Anchor to Use in a grid layoutUse in a grid layout

Build a product image gallery with consistent sizing using grid. This example arranges three product photos in a row, each constrained to a square with rounded corners so they line up evenly.

Preview

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>

Anchor to Useful forUseful for

Adding illustrations and photos.

Anchor to Best practicesBest practices

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

Anchor to Content guidelinesContent 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".

Was this page helpful?