Choose a version:

Image
component

The Image component renders an image for the Storefront API's Image object by using the data prop. You can customize this component using passthrough props.

Images default to being responsive automatically (width: 100%, height: auto), and expect an aspectRatio prop, which ensures your image doesn't create any layout shift. For fixed-size images, you can set width to an exact value, and a srcSet with 1x, 2x, and 3x DPI variants will automatically be generated for you.

Anchor to propsProps

Anchor to aspectRatio aspectRatio string: The aspect ratio of the image, in the format of width/height.
Anchor to crop crop Default: `center`: The crop position of the image.
Anchor to data data PartialDeep<ImageType, {recurseIntoArrays: true}>: Data mapping to the Storefront API Image object. Must be an Image object.
Anchor to loader loader: A function that returns a URL string for an image.
Anchor to srcSetOptions srcSetOptions: An optional prop you can use to change the default srcSet generation behaviour

HydrogenImageBaseProps

aspectRatio
The aspect ratio of the image, in the format of `width/height`.
```
string
```
crop
The crop position of the image.
```
Crop
```
data
Data mapping to the [Storefront API `Image`](https://shopify.dev/docs/api/storefront/2025-04/objects/Image) object. Must be an Image object.
```
PartialDeep<ImageType, {recurseIntoArrays: true}>
```
loader
A function that returns a URL string for an image.
```
Loader
```
srcSetOptions
An optional prop you can use to change the default srcSet generation behaviour
```
SrcSetOptions
```

{
  /** The aspect ratio of the image, in the format of `width/height`.
   *
   * @example
   * ```
   * <Image data={productImage} aspectRatio="4/5" />
   * ```
   */
  aspectRatio?: string;
  /** The crop position of the image.
   *
   * @remarks
   * In the event that AspectRatio is set, without specifying a crop,
   * the Shopify CDN won't return the expected image.
   *
   * @defaultValue `center`
   */
  crop?: Crop;
  /** Data mapping to the [Storefront API `Image`](https://shopify.dev/docs/api/storefront/2025-04/objects/Image) object. Must be an Image object.
   *
   * @example
   * ```
   * import {IMAGE_FRAGMENT, Image} from '@shopify/hydrogen';
   *
   * export const IMAGE_QUERY = `#graphql
   * ${IMAGE_FRAGMENT}
   * query {
   *   product {
   *     featuredImage {
   *       ...Image
   *     }
   *   }
   * }`
   *
   * <Image
   *   data={productImage}
   *   sizes="(min-width: 45em) 50vw, 100vw"
   *   aspectRatio="4/5"
   * />
   * ```
   *
   * Image: {@link https://shopify.dev/api/storefront/reference/common-objects/image}
   */
  data?: PartialDeep<ImageType, {recurseIntoArrays: true}>;
  /** A function that returns a URL string for an image.
   *
   * @remarks
   * By default, this uses Shopify’s CDN {@link https://cdn.shopify.com/} but you can provide
   * your own function to use a another provider, as long as they support URL based image transformations.
   */
  loader?: Loader;
  /** An optional prop you can use to change the default srcSet generation behaviour */
  srcSetOptions?: SrcSetOptions;
}

Crop

'center' | 'top' | 'bottom' | 'left' | 'right'

Loader

params
```
LoaderParams
```

string

string

export type Loader = (params: LoaderParams) => string;

LoaderParams

crop
The URL param that controls the cropping region
```
Crop
```
height
The URL param that controls height
```
number
```
src
The base URL of the image
```
string
```
width
The URL param that controls width
```
number
```

{
  /** The base URL of the image */
  src?: ImageType['url'];
  /** The URL param that controls width */
  width?: number;
  /** The URL param that controls height */
  height?: number;
  /** The URL param that controls the cropping region */
  crop?: Crop;
}

SrcSetOptions

incrementSize
The increment by which to increase for each size, in pixels
```
number
```
intervals
The number of sizes to generate
```
number
```
placeholderWidth
The size used for placeholder fallback images
```
number
```
startingWidth
The smallest image size
```
number
```

{
  /** The number of sizes to generate */
  intervals: number;
  /** The smallest image size */
  startingWidth: number;
  /** The increment by which to increase for each size, in pixels */
  incrementSize: number;
  /** The size used for placeholder fallback images */
  placeholderWidth: number;
}

Was this section helpful?

Example code

import {Image} from '@shopify/hydrogen';

// An example query

const IMAGE_QUERY = `#graphql

query {

product {

featuredImage {

altText

url

height

width

}

export default function ProductImage({product}) {

if (!product.featuredImage) {

return null;

}

return (

<Image

data={product.featuredImage}

sizes="(min-width: 45em) 50vw, 100vw"

aspectRatio="4/5"

);

}

examples

Example code

description

I am the default example

JavaScript

import {Image} from '@shopify/hydrogen';

// An example query
const IMAGE_QUERY = `#graphql
  query {
    product {
      featuredImage {
        altText
        url
        height
        width
      }
    }
  }
`;

export default function ProductImage({product}) {
  if (!product.featuredImage) {
    return null;
  }

  return (
    <Image
      data={product.featuredImage}
      sizes="(min-width: 45em) 50vw, 100vw"
      aspectRatio="4/5"
    />
  );
}

TypeScript

import React from 'react';
import {Image} from '@shopify/hydrogen';
import type {Product} from '@shopify/hydrogen/storefront-api-types';

// An example query
const IMAGE_QUERY = `#graphql
  query {
    product {
      featuredImage {
        altText
        url
        height
        width
      }
    }
  }
`;

export default function ProductImage({product}: {product: Product}) {
  if (!product.featuredImage) {
    return null;
  }

  return (
    <Image
      data={product.featuredImage}
      sizes="(min-width: 45em) 50vw, 100vw"
      aspectRatio="4/5"
    />
  );
}

Anchor to relatedRelated

MediaFile

Imagecomponent

Anchor to propsProps

HydrogenImageBaseProps

Crop

Loader

LoaderParams

SrcSetOptions

examples

Example code

description

JavaScript

TypeScript

Anchor to relatedRelated

Image
component