@shopify/hydrogen-react 2026.4.1 → 2026.4.2

package/dist/browser-prod/Image.mjs

@@ -1,6 +1,10 @@
-import { jsx } from "react/jsx-runtime";
 import * as React from "react";
-const IMAGE_FRAGMENT = `#graphql
+import { jsx } from "react/jsx-runtime";
+//#region src/Image.tsx
+/**
+* A Storefront API GraphQL fragment that can be used to query for an image.
+*/
+var IMAGE_FRAGMENT = `#graphql
   fragment Image on Image {
     altText
     url
@@ -8,344 +12,341 @@ const IMAGE_FRAGMENT = `#graphql
     height
   }
 `;
-const Image = React.forwardRef(
-  ({
-    alt,
-    aspectRatio,
-    crop = "center",
-    data,
-    decoding = "async",
-    height = "auto",
-    loader = shopifyLoader,
-    loading = "lazy",
-    sizes,
-    src,
-    srcSetOptions = {
-      intervals: 15,
-      startingWidth: 200,
-      incrementSize: 200,
-      placeholderWidth: 100
-    },
-    width = "100%",
-    ...passthroughProps
-  }, ref) => {
-    const normalizedData = React.useMemo(() => {
-      const dataWidth = (data == null ? void 0 : data.width) && (data == null ? void 0 : data.height) ? data == null ? void 0 : data.width : void 0;
-      const dataHeight = (data == null ? void 0 : data.width) && (data == null ? void 0 : data.height) ? data == null ? void 0 : data.height : void 0;
-      return {
-        width: dataWidth,
-        height: dataHeight,
-        unitsMatch: Boolean(unitsMatch(dataWidth, dataHeight))
-      };
-    }, [data]);
-    const normalizedProps = React.useMemo(() => {
-      const nWidthProp = width || "100%";
-      const widthParts = getUnitValueParts(nWidthProp.toString());
-      const nWidth = `${widthParts.number}${widthParts.unit}`;
-      const autoHeight = height === void 0 || height === null;
-      const heightParts = autoHeight ? null : getUnitValueParts(height.toString());
-      const fixedHeight = heightParts ? `${heightParts.number}${heightParts.unit}` : "";
-      const nHeight = autoHeight ? "auto" : fixedHeight;
-      const nSrc = src || (data == null ? void 0 : data.url);
-      const nAlt = (data == null ? void 0 : data.altText) && !alt ? data == null ? void 0 : data.altText : alt || "";
-      const nAspectRatio = aspectRatio ? aspectRatio : normalizedData.unitsMatch ? [
-        getNormalizedFixedUnit(normalizedData.width),
-        getNormalizedFixedUnit(normalizedData.height)
-      ].join("/") : void 0;
-      return {
-        width: nWidth,
-        height: nHeight,
-        src: nSrc,
-        alt: nAlt,
-        aspectRatio: nAspectRatio
-      };
-    }, [
-      width,
-      height,
-      src,
-      data,
-      alt,
-      aspectRatio,
-      normalizedData,
-      passthroughProps == null ? void 0 : passthroughProps.key
-    ]);
-    const { intervals, startingWidth, incrementSize, placeholderWidth } = srcSetOptions;
-    const imageWidths = React.useMemo(() => {
-      return generateImageWidths(
-        width,
-        intervals,
-        startingWidth,
-        incrementSize
-      );
-    }, [width, intervals, startingWidth, incrementSize]);
-    const fixedWidth = isFixedWidth(normalizedProps.width);
-    if (fixedWidth) {
-      return /* @__PURE__ */ jsx(
-        FixedWidthImage,
-        {
-          aspectRatio,
-          crop,
-          decoding,
-          height,
-          imageWidths,
-          loader,
-          loading,
-          normalizedProps,
-          passthroughProps,
-          ref,
-          width,
-          data
-        }
-      );
-    } else {
-      return /* @__PURE__ */ jsx(
-        FluidImage,
-        {
-          aspectRatio,
-          crop,
-          decoding,
-          imageWidths,
-          loader,
-          loading,
-          normalizedProps,
-          passthroughProps,
-          placeholderWidth,
-          ref,
-          sizes,
-          data
-        }
-      );
-    }
-  }
-);
-const FixedWidthImage = React.forwardRef(
-  ({
-    aspectRatio,
-    crop,
-    decoding,
-    height,
-    imageWidths,
-    loader = shopifyLoader,
-    loading,
-    normalizedProps,
-    passthroughProps,
-    width,
-    data
-  }, ref) => {
-    const fixed = React.useMemo(() => {
-      const intWidth = getNormalizedFixedUnit(width);
-      const intHeight = getNormalizedFixedUnit(height);
-      const fixedAspectRatio = aspectRatio ? aspectRatio : unitsMatch(normalizedProps.width, normalizedProps.height) ? [intWidth, intHeight].join("/") : normalizedProps.aspectRatio ? normalizedProps.aspectRatio : void 0;
-      const sizesArray = imageWidths === void 0 ? void 0 : generateSizes(imageWidths, fixedAspectRatio, crop, {
-        width: (data == null ? void 0 : data.width) ?? void 0,
-        height: (data == null ? void 0 : data.height) ?? void 0
-      });
-      const fixedHeight = intHeight ? intHeight : fixedAspectRatio && intWidth ? intWidth * (parseAspectRatio(fixedAspectRatio) ?? 1) : void 0;
-      const srcSet = generateSrcSet(normalizedProps.src, sizesArray, loader);
-      const src = loader({
-        src: normalizedProps.src,
-        width: intWidth,
-        height: fixedHeight,
-        crop: normalizedProps.height === "auto" ? void 0 : crop
-      });
-      return {
-        width: intWidth,
-        aspectRatio: fixedAspectRatio,
-        height: fixedHeight,
-        srcSet,
-        src
-      };
-    }, [
-      aspectRatio,
-      crop,
-      data,
-      height,
-      imageWidths,
-      loader,
-      normalizedProps,
-      width
-    ]);
-    return /* @__PURE__ */ jsx(
-      "img",
-      {
-        ref,
-        alt: normalizedProps.alt,
-        decoding,
-        height: fixed.height,
-        loading,
-        src: fixed.src,
-        srcSet: fixed.srcSet,
-        width: fixed.width,
-        style: {
-          aspectRatio: fixed.aspectRatio,
-          ...passthroughProps.style
-        },
-        ...passthroughProps
-      }
-    );
-  }
-);
-const FluidImage = React.forwardRef(
-  ({
-    crop,
-    decoding,
-    imageWidths,
-    loader = shopifyLoader,
-    loading,
-    normalizedProps,
-    passthroughProps,
-    placeholderWidth,
-    sizes,
-    data
-  }, ref) => {
-    const fluid = React.useMemo(() => {
-      const sizesArray = imageWidths === void 0 ? void 0 : generateSizes(imageWidths, normalizedProps.aspectRatio, crop, {
-        width: (data == null ? void 0 : data.width) ?? void 0,
-        height: (data == null ? void 0 : data.height) ?? void 0
-      });
-      const placeholderHeight = normalizedProps.aspectRatio && placeholderWidth ? placeholderWidth * (parseAspectRatio(normalizedProps.aspectRatio) ?? 1) : void 0;
-      const srcSet = generateSrcSet(normalizedProps.src, sizesArray, loader);
-      const src = loader({
-        src: normalizedProps.src,
-        width: placeholderWidth,
-        height: placeholderHeight,
-        crop
-      });
-      return {
-        placeholderHeight,
-        srcSet,
-        src
-      };
-    }, [crop, data, imageWidths, loader, normalizedProps, placeholderWidth]);
-    return /* @__PURE__ */ jsx(
-      "img",
-      {
-        ref,
-        alt: normalizedProps.alt,
-        decoding,
-        height: fluid.placeholderHeight,
-        loading,
-        sizes,
-        src: fluid.src,
-        srcSet: fluid.srcSet,
-        width: placeholderWidth,
-        ...passthroughProps,
-        style: {
-          width: normalizedProps.width,
-          aspectRatio: normalizedProps.aspectRatio,
-          ...passthroughProps.style
-        }
-      }
-    );
-  }
-);
-const PLACEHOLDER_DOMAIN = "https://placeholder.shopify.com";
+/**
+* Hydrogen’s Image component is a wrapper around the HTML image element.
+* It supports the same props as the HTML `img` element, but automatically
+* generates the srcSet and sizes attributes for you. For most use cases,
+* you’ll want to set the `aspectRatio` prop to ensure the image is sized
+* correctly.
+*
+* @remarks
+* - `decoding` is set to `async` by default.
+* - `loading` is set to `lazy` by default.
+* - `alt` will automatically be set to the `altText` from the Storefront API if passed in the `data` prop
+* - `src` will automatically be set to the `url` from the Storefront API if passed in the `data` prop
+*
+* @example
+* A responsive image with a 4:5 aspect ratio:
+* ```
+* <Image
+*   data={product.featuredImage}
+*   aspectRatio="4/5"
+*   sizes="(min-width: 45em) 40vw, 100vw"
+* />
+* ```
+* @example
+* A fixed size image:
+* ```
+* <Image
+*   data={product.featuredImage}
+*   width={100}
+*   height={100}
+* />
+* ```
+*
+* {@link https://shopify.dev/docs/api/hydrogen-react/components/image}
+* @publicDocs
+*/
+var Image = React.forwardRef(({ alt, aspectRatio, crop = "center", data, decoding = "async", height = "auto", loader = shopifyLoader, loading = "lazy", sizes, src, srcSetOptions = {
+	intervals: 15,
+	startingWidth: 200,
+	incrementSize: 200,
+	placeholderWidth: 100
+}, width = "100%", ...passthroughProps }, ref) => {
+	const normalizedData = React.useMemo(() => {
+		const dataWidth = data?.width && data?.height ? data?.width : void 0;
+		const dataHeight = data?.width && data?.height ? data?.height : void 0;
+		return {
+			width: dataWidth,
+			height: dataHeight,
+			unitsMatch: Boolean(unitsMatch(dataWidth, dataHeight))
+		};
+	}, [data]);
+	const normalizedProps = React.useMemo(() => {
+		const widthParts = getUnitValueParts((width || "100%").toString());
+		const nWidth = `${widthParts.number}${widthParts.unit}`;
+		const autoHeight = height === void 0 || height === null;
+		const heightParts = autoHeight ? null : getUnitValueParts(height.toString());
+		const fixedHeight = heightParts ? `${heightParts.number}${heightParts.unit}` : "";
+		return {
+			width: nWidth,
+			height: autoHeight ? "auto" : fixedHeight,
+			src: src || data?.url,
+			alt: data?.altText && !alt ? data?.altText : alt || "",
+			aspectRatio: aspectRatio ? aspectRatio : normalizedData.unitsMatch ? [getNormalizedFixedUnit(normalizedData.width), getNormalizedFixedUnit(normalizedData.height)].join("/") : void 0
+		};
+	}, [
+		width,
+		height,
+		src,
+		data,
+		alt,
+		aspectRatio,
+		normalizedData,
+		passthroughProps?.key
+	]);
+	const { intervals, startingWidth, incrementSize, placeholderWidth } = srcSetOptions;
+	const imageWidths = React.useMemo(() => {
+		return generateImageWidths(width, intervals, startingWidth, incrementSize);
+	}, [
+		width,
+		intervals,
+		startingWidth,
+		incrementSize
+	]);
+	if (isFixedWidth(normalizedProps.width)) return /* @__PURE__ */ jsx(FixedWidthImage, {
+		aspectRatio,
+		crop,
+		decoding,
+		height,
+		imageWidths,
+		loader,
+		loading,
+		normalizedProps,
+		passthroughProps,
+		ref,
+		width,
+		data
+	});
+	else return /* @__PURE__ */ jsx(FluidImage, {
+		aspectRatio,
+		crop,
+		decoding,
+		imageWidths,
+		loader,
+		loading,
+		normalizedProps,
+		passthroughProps,
+		placeholderWidth,
+		ref,
+		sizes,
+		data
+	});
+});
+var FixedWidthImage = React.forwardRef(({ aspectRatio, crop, decoding, height, imageWidths, loader = shopifyLoader, loading, normalizedProps, passthroughProps, width, data }, ref) => {
+	const fixed = React.useMemo(() => {
+		const intWidth = getNormalizedFixedUnit(width);
+		const intHeight = getNormalizedFixedUnit(height);
+		const fixedAspectRatio = aspectRatio ? aspectRatio : unitsMatch(normalizedProps.width, normalizedProps.height) ? [intWidth, intHeight].join("/") : normalizedProps.aspectRatio ? normalizedProps.aspectRatio : void 0;
+		const sizesArray = imageWidths === void 0 ? void 0 : generateSizes(imageWidths, fixedAspectRatio, crop, {
+			width: data?.width ?? void 0,
+			height: data?.height ?? void 0
+		});
+		const fixedHeight = intHeight ? intHeight : fixedAspectRatio && intWidth ? intWidth * (parseAspectRatio(fixedAspectRatio) ?? 1) : void 0;
+		return {
+			width: intWidth,
+			aspectRatio: fixedAspectRatio,
+			height: fixedHeight,
+			srcSet: generateSrcSet(normalizedProps.src, sizesArray, loader),
+			src: loader({
+				src: normalizedProps.src,
+				width: intWidth,
+				height: fixedHeight,
+				crop: normalizedProps.height === "auto" ? void 0 : crop
+			})
+		};
+	}, [
+		aspectRatio,
+		crop,
+		data,
+		height,
+		imageWidths,
+		loader,
+		normalizedProps,
+		width
+	]);
+	return /* @__PURE__ */ jsx("img", {
+		ref,
+		alt: normalizedProps.alt,
+		decoding,
+		height: fixed.height,
+		loading,
+		src: fixed.src,
+		srcSet: fixed.srcSet,
+		width: fixed.width,
+		style: {
+			aspectRatio: fixed.aspectRatio,
+			...passthroughProps.style
+		},
+		...passthroughProps
+	});
+});
+var FluidImage = React.forwardRef(({ crop, decoding, imageWidths, loader = shopifyLoader, loading, normalizedProps, passthroughProps, placeholderWidth, sizes, data }, ref) => {
+	const fluid = React.useMemo(() => {
+		const sizesArray = imageWidths === void 0 ? void 0 : generateSizes(imageWidths, normalizedProps.aspectRatio, crop, {
+			width: data?.width ?? void 0,
+			height: data?.height ?? void 0
+		});
+		const placeholderHeight = normalizedProps.aspectRatio && placeholderWidth ? placeholderWidth * (parseAspectRatio(normalizedProps.aspectRatio) ?? 1) : void 0;
+		return {
+			placeholderHeight,
+			srcSet: generateSrcSet(normalizedProps.src, sizesArray, loader),
+			src: loader({
+				src: normalizedProps.src,
+				width: placeholderWidth,
+				height: placeholderHeight,
+				crop
+			})
+		};
+	}, [
+		crop,
+		data,
+		imageWidths,
+		loader,
+		normalizedProps,
+		placeholderWidth
+	]);
+	return /* @__PURE__ */ jsx("img", {
+		ref,
+		alt: normalizedProps.alt,
+		decoding,
+		height: fluid.placeholderHeight,
+		loading,
+		sizes,
+		src: fluid.src,
+		srcSet: fluid.srcSet,
+		width: placeholderWidth,
+		...passthroughProps,
+		style: {
+			width: normalizedProps.width,
+			aspectRatio: normalizedProps.aspectRatio,
+			...passthroughProps.style
+		}
+	});
+});
+/**
+* The shopifyLoader function is a simple utility function that takes a src, width,
+* height, and crop and returns a string that can be used as the src for an image.
+* It can be used with the Hydrogen Image component or with the next/image component.
+* (or any others that accept equivalent configuration)
+* @param src - The source URL of the image, e.g. `https://cdn.shopify.com/static/sample-images/garnished.jpeg`
+* @param width - The width of the image, e.g. `100`
+* @param height - The height of the image, e.g. `100`
+* @param crop - The crop of the image, e.g. `center`
+* @returns A Shopify image URL with the correct query parameters, e.g. `https://cdn.shopify.com/static/sample-images/garnished.jpeg?width=100&height=100&crop=center`
+*
+* @example
+* ```
+* shopifyLoader({
+*   src: 'https://cdn.shopify.com/static/sample-images/garnished.jpeg',
+*   width: 100,
+*   height: 100,
+*   crop: 'center',
+* })
+* ```
+*/
+var PLACEHOLDER_DOMAIN = "https://placeholder.shopify.com";
 function shopifyLoader({ src, width, height, crop }) {
-  if (!src) {
-    return "";
-  }
-  const url = new URL(src, PLACEHOLDER_DOMAIN);
-  if (width) {
-    url.searchParams.append("width", Math.round(width).toString());
-  }
-  if (height) {
-    url.searchParams.append("height", Math.round(height).toString());
-  }
-  if (crop) {
-    url.searchParams.append("crop", crop);
-  }
-  return url.href.replace(PLACEHOLDER_DOMAIN, "");
+	if (!src) return "";
+	const url = new URL(src, PLACEHOLDER_DOMAIN);
+	if (width) url.searchParams.append("width", Math.round(width).toString());
+	if (height) url.searchParams.append("height", Math.round(height).toString());
+	if (crop) url.searchParams.append("crop", crop);
+	return url.href.replace(PLACEHOLDER_DOMAIN, "");
 }
+/**
+* Checks whether the width and height share the same unit type
+* @param width - The width of the image, e.g. 100% | 10px
+* @param height - The height of the image, e.g. auto | 100px
+* @returns Whether the width and height share the same unit type (boolean)
+*/
 function unitsMatch(width = "100%", height = "auto") {
-  return getUnitValueParts(width.toString()).unit === getUnitValueParts(height.toString()).unit;
+	return getUnitValueParts(width.toString()).unit === getUnitValueParts(height.toString()).unit;
 }
+/**
+* Given a CSS size, returns the unit and number parts of the value
+* @param value - The CSS size, e.g. 100px
+* @returns The unit and number parts of the value, e.g. \{unit: 'px', number: 100\}
+*/
 function getUnitValueParts(value) {
-  const unit = value.replace(/[0-9.]/g, "");
-  const number = parseFloat(value.replace(unit, ""));
-  return {
-    unit: unit === "" ? number === void 0 ? "auto" : "px" : unit,
-    number
-  };
+	const unit = value.replace(/[0-9.]/g, "");
+	const number = parseFloat(value.replace(unit, ""));
+	return {
+		unit: unit === "" ? number === void 0 ? "auto" : "px" : unit,
+		number
+	};
 }
+/**
+* Given a value, returns the width of the image as an integer in pixels
+* @param value - The width of the image, e.g. 16px | 1rem | 1em | 16
+* @returns The width of the image in pixels, e.g. 16, or undefined if the value is not a fixed unit
+*/
 function getNormalizedFixedUnit(value) {
-  if (value === void 0) {
-    return;
-  }
-  const { unit, number } = getUnitValueParts(value.toString());
-  switch (unit) {
-    case "em":
-      return number * 16;
-    case "rem":
-      return number * 16;
-    case "px":
-      return number;
-    case "":
-      return number;
-    default:
-      return;
-  }
+	if (value === void 0) return;
+	const { unit, number } = getUnitValueParts(value.toString());
+	switch (unit) {
+		case "em": return number * 16;
+		case "rem": return number * 16;
+		case "px": return number;
+		case "": return number;
+		default: return;
+	}
 }
+/**
+* This function checks whether a width is fixed or not.
+* @param width - The width of the image, e.g. 100 | '100px' | '100em' | '100rem'
+* @returns Whether the width is fixed or not
+*/
 function isFixedWidth(width) {
-  const fixedEndings = /\d(px|em|rem)$/;
-  return typeof width === "number" || fixedEndings.test(width);
+	return typeof width === "number" || /\d(px|em|rem)$/.test(width);
 }
+/**
+* This function generates a srcSet for Shopify images.
+* @param src - The source URL of the image, e.g. https://cdn.shopify.com/static/sample-images/garnished.jpeg
+* @param sizesArray - An array of objects containing the `width`, `height`, and `crop` of the image, e.g. [\{width: 200, height: 200, crop: 'center'\}, \{width: 400, height: 400, crop: 'center'\}]
+* @param loader - A function that takes a Shopify image URL and returns a Shopify image URL with the correct query parameters
+* @returns A srcSet for Shopify images, e.g. 'https://cdn.shopify.com/static/sample-images/garnished.jpeg?width=200&height=200&crop=center 200w, https://cdn.shopify.com/static/sample-images/garnished.jpeg?width=400&height=400&crop=center 400w'
+*/
 function generateSrcSet(src, sizesArray, loader = shopifyLoader) {
-  if (!src) {
-    return "";
-  }
-  if ((sizesArray == null ? void 0 : sizesArray.length) === 0 || !sizesArray) {
-    return src;
-  }
-  return sizesArray.map(
-    (size, i) => `${loader({
-      src,
-      width: size.width,
-      height: size.height,
-      crop: size.crop
-    })} ${sizesArray.length === 3 ? `${i + 1}x` : `${size.width ?? 0}w`}`
-  ).join(`, `);
+	if (!src) return "";
+	if (sizesArray?.length === 0 || !sizesArray) return src;
+	return sizesArray.map((size, i) => `${loader({
+		src,
+		width: size.width,
+		height: size.height,
+		crop: size.crop
+	})} ${sizesArray.length === 3 ? `${i + 1}x` : `${size.width ?? 0}w`}`).join(`, `);
 }
+/**
+* This function generates an array of sizes for Shopify images, for both fixed and responsive images.
+* @param width - The CSS width of the image
+* @param intervals - The number of intervals to generate
+* @param startingWidth - The starting width of the image
+* @param incrementSize - The size of each interval
+* @returns An array of widths
+*/
 function generateImageWidths(width = "100%", intervals, startingWidth, incrementSize) {
-  const responsive = Array.from(
-    { length: intervals },
-    (_, i) => i * incrementSize + startingWidth
-  );
-  const fixed = Array.from(
-    { length: 3 },
-    (_, i) => (i + 1) * (getNormalizedFixedUnit(width) ?? 0)
-  );
-  return isFixedWidth(width) ? fixed : responsive;
+	const responsive = Array.from({ length: intervals }, (_, i) => i * incrementSize + startingWidth);
+	const fixed = Array.from({ length: 3 }, (_, i) => (i + 1) * (getNormalizedFixedUnit(width) ?? 0));
+	return isFixedWidth(width) ? fixed : responsive;
 }
+/**
+* Simple utility function to convert an aspect ratio CSS string to a decimal, currently only supports values like `1/1`, not `0.5`, or `auto`
+* @param aspectRatio - The aspect ratio of the image, e.g. `1/1`
+* @returns The aspect ratio as a number, e.g. `0.5`
+*
+* {@link https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio}
+*/
 function parseAspectRatio(aspectRatio) {
-  if (!aspectRatio) return;
-  const [width, height] = aspectRatio.split("/");
-  return 1 / (Number(width) / Number(height));
+	if (!aspectRatio) return;
+	const [width, height] = aspectRatio.split("/");
+	return 1 / (Number(width) / Number(height));
 }
 function generateSizes(imageWidths, aspectRatio, crop = "center", sourceDimensions) {
-  if (!imageWidths) return;
-  return imageWidths.map((width) => {
-    return {
-      width,
-      height: aspectRatio ? width * (parseAspectRatio(aspectRatio) ?? 1) : void 0,
-      crop
-    };
-  }).filter(({ width, height }) => {
-    if ((sourceDimensions == null ? void 0 : sourceDimensions.width) && width > sourceDimensions.width) {
-      return false;
-    }
-    if ((sourceDimensions == null ? void 0 : sourceDimensions.height) && height && height > sourceDimensions.height) {
-      return false;
-    }
-    return true;
-  });
+	if (!imageWidths) return;
+	return imageWidths.map((width) => {
+		return {
+			width,
+			height: aspectRatio ? width * (parseAspectRatio(aspectRatio) ?? 1) : void 0,
+			crop
+		};
+	}).filter(({ width, height }) => {
+		if (sourceDimensions?.width && width > sourceDimensions.width) return false;
+		if (sourceDimensions?.height && height && height > sourceDimensions.height) return false;
+		return true;
+	});
 }
-export {
-  IMAGE_FRAGMENT,
-  Image,
-  generateImageWidths,
-  generateSizes,
-  generateSrcSet,
-  parseAspectRatio,
-  shopifyLoader
-};
-//# sourceMappingURL=Image.mjs.map
+//#endregion
+export { IMAGE_FRAGMENT, Image, shopifyLoader };
+
+//# sourceMappingURL=Image.mjs.map