Use the Dynamic Imaging Service (DIS) and the <DynamicImage> component to deliver optimized, responsive images in your storefront. DIS formats the correct size for each image application and eliminates the need of uploading multiple images with different sizes.
Images are typically the largest contributor to page weight. Unoptimized images degrade Core Web Vitals by increasing Largest Contentful Paint (LCP) and slowing Time to Interactive (TTI). Storefront Next provides built-in DIS integration that handles format conversion, server-side resizing, and responsive source generation automatically.
Dynamic Imaging Service (DIS)
Salesforce B2C Commerce’s Dynamic Imaging Service (DIS) is an image transformation service that optimizes images on-the-fly. Instead of storing pre-generated image variants, DIS transforms images at request time based on URL parameters. CDNs in front of DIS cache the transformed results at the edge.
DIS provides:
Format conversion: Serves modern formats like WebP (25–35% smaller than JPEG/PNG) with automatic fallback.
Server-side resizing: Sends each device exactly the pixels it needs.
Quality control: Balances visual fidelity against file size.
DIS URL Anatomy
Storefront Next rewrites static B2C Commerce image URLs into DIS URLs with transformation parameters:
When enableDis is false, the image system falls back to serving static assets directly. Format conversion, server-side resizing, and <source> generation are all skipped.
Image Filtering on Product Listing Pages
Search responses (fetchSearchProducts) include an imageGroups array on every hit. By default, B2 Commerce API (SCAPI) returns every imageGroup for every variant, which on variant-heavy catalogs can be the dominant contributor to PLP payload size—most of those images are never rendered.
The template restricts the response via SCAPI’s imgTypes query parameter using config.server.ts:
Each role names the viewType a specific consumer reads: tile for the product tile hero, and swatch for the color thumbnails. The search filter derives its imgTypes query parameter as the union of these values (deduplicated and joined with ,), so adding a new role automatically widens the filter. Setting a role to undefined opts that role out. Setting all roles to undefined, or providing an empty images: {}, disables filtering entirely and returns the full payload. imgTypes requires expand=images and allImages=true—both are set by fetchSearchProducts.
Keeping Role-Named Values Aligned with Consumers
If you customize the product tile to read a different viewType (for example, switch the hero from medium to large), you must update the matching role here. Otherwise, the tile will receive empty image arrays for the unrequested viewType. The built-in consumers that should eventually read from these declarations are:
tile in src/components/product-image/index.tsx (currently hardcodes 'medium')
swatch in src/lib/product/product-utils.ts (getDecoratedVariationAttributes, defaults swatchViewType to 'swatch')
The hardcoded strings in those consumers are tracked for a followup cleanup that derives them from these same role-named declarations, eliminating drift.
DynamicImage Component
<DynamicImage> is a responsive image component that generates an optimized <picture> element with DIS-powered <source> elements and responsive preloading via React 19’s preload() API.
This renders a <picture> element with <source> elements sized per breakpoint, each requesting a DIS-resized WebP variant with 1x and 2x srcSet descriptors.
The src Prop and Placeholder Syntax
The src prop accepts plain URLs or URLs with placeholder syntax: bracket-delimited segments that DynamicImage replaces with computed values.
1// Plain URL. DynamicImage appends sw/sh/q params automatically2<DynamicImage src="https://example.com/image.jpg" widths={[400, 800]} />34// Placeholder syntax. {width} and {height} are replaced per breakpoint5<DynamicImage src="https://example.com/image.jpg[?sw={width}&sh={height}]" widths={[400, 800]} heights={[300, 600]} />67// Inline placeholder in path segment8<DynamicImage src="https://example.com/image[_{width}].jpg" widths={[400, 800]} />
The bracket syntax [...] marks optional URL segments that are stripped when no dimensions are provided.
Responsive Widths
The widths prop controls how wide each <source> requests its image from DIS. It determines the sw parameter value and the sizes attribute in the generated markup. It accepts three formats:
Use fixed px widths when the image container has a predetermined size (for example, carousels). Use vw-based widths when the image scales with the viewport (for example, product grids, hero banners).
Server-Side Scaling with Heights
The heights prop enables DIS server-side scaling via the sh parameter. When provided alongside widths, it defines exact output dimensions, giving you precise aspect ratio control across responsive breakpoints.
1// 4:3 aspect ratio maintained across all breakpoints2<DynamicImage3 src="https://example.com/image.jpg[?sw={width}&sh={height}]"4 widths={[400, 800, 1200]}5 heights={[300, 600, 900]}6/>
Both values are multiplied by the DPR factor. At 2x, widths={[400]} and heights={[300]} generates srcSet entries for sw=400&sh=300 (1x) and sw=800&sh=600 (2x).
heights supports the same formats as widths (arrays, objects with breakpoint keys).
When heights is omitted, DIS preserves the original aspect ratio based on sw alone.
Loading Priority and Preloading
DynamicImage integrates with React 19’s preload() to emit <link rel="preload"> hints for high-priority images during server rendering:
1// Explicitly high priority. Preloaded during SSR, loaded eagerly.2<DynamicImage src={heroImage} widths={[...]} priority="high" loading="eager" />34// Auto priority (default). Determined by DynamicImageProvider context.5<DynamicImage src={productImage} widths={[...]} />67// Explicitly low priority. Lazy-loaded, no preload hints.8<DynamicImage src={belowFoldImage} widths={[...]} priority="low" loading="lazy" />
When priority isn’t set, the component checks the DynamicImageProvider context to determine whether the image should be treated as high priority. If no context is present, it defaults to 'auto' priority with loading="lazy".
DynamicImageProvider Context
The DynamicImageProvider is an optional React context that controls image priority and dimensions for nested <DynamicImage> components. It solves a practical problem: in deep component trees (for example, product grid → product tile → product image), determining whether an image is above-the-fold requires knowledge the image component itself doesn’t have. The provider bridges that gap by separating the decision about importance from the rendering of individual images.
1import DynamicImageProvider from "@/providers/dynamic-image";
How It Works
The provider exposes two interfaces: one for the outer container that sets up the context, and one for the nested consumers that interact with it.
Container interface (passed via value prop):
1value: {2 sources?: Set<string>; // Shared source registry3 widths?: DynamicImageDimensions; // Responsive widths for all nested images4 heights?: DynamicImageDimensions; // Responsive heights for all nested images5 addSource?: (src: string, sources: Set<string>)=> boolean; // Strategy: how to register an image6 hasSource?: (src: string, sources: Set<string>)=> boolean; // Strategy: how to determine importance7}
The container receives the raw Set<string> alongside each src, giving it full control over the registration and lookup logic.
Consumer interface (returned by useDynamicImageContext()):
1{2 addSource: (src: string)=> boolean; // Register this image3 hasSource: (src: string)=> boolean; // Is this image important?4 widths: DynamicImageDimensions | undefined;5 heights: DynamicImageDimensions | undefined;6}
Consumers never see the Set or the strategy. They call addSource(src) to register and read widths/heights for their dimensions. The <DynamicImage> component calls hasSource(src) internally: when it returns true, the image is promoted to priority="high" and loading="eager".
This separation means the container owns all priority decisions while nested components remain generic and reusable.
Example: Product Grid with Critical and Non-Critical Images
Split product grid tiles into critical (above-the-fold) and non-critical (below-the-fold) batches:
1const responsiveImageWidths = [2 '40vw', // base: 2 columns3 '25vw', // sm: 3 columns4 '18vw', // md: 4 columns5 '14vw', // lg: 4 columns with refinement panel6 '16vw', // xl7 '16vw', // 2xl8];910// Critical tiles: all images are high priority11const hasSource = useCallback(()=> true, []);1213<DynamicImageProvider value={{hasSource, widths: responsiveImageWidths}}>14{criticalProducts.map(product =><ProductTile ... />)}15</DynamicImageProvider>1617// Non-critical tiles: no hasSource → all images default to lazy18<DynamicImageProvider value={{widths: responsiveImageWidths}}>19{nonCriticalProducts.map(product =><ProductTile ... />)}20</DynamicImageProvider>
The ProductTile component itself is identical in both batches. It doesn’t know whether it’s above or below the fold. The provider controls that from the outside.
Example: Capping High-Priority Images with a Single Provider
A single provider can use the shared Set<string> to cap how many images are promoted. This example treats only the first row of a four-column grid as high priority:
The first four tiles to call addSource get registered. When <DynamicImage> later calls hasSource, only those four return true.
Utility Functions
The @/lib/images/dynamic-image module exports utilities for working with DIS URLs outside the <DynamicImage> component. Use these when you need to transform image URLs programmatically, for example in content slots or rich text from SCAPI.
Performance Checklist
Follow these guidelines to get the best performance from your storefront images:
Use modern image formats: Modern image formats like WebP give 25–35% smaller files than JPEG/PNG. A fallbackFormat config allows the definition of an automatic fallback format for browsers that don’t support any of the <source> formats.
Above the fold: Set priority="high" and loading="eager" on LCP-candidate images. This triggers React 19 SSR preloading.
Below the fold: Use loading="lazy". Omit priority or set priority="low".
Always set widths or heights: Without either, <DynamicImage> renders a plain <img> with no responsive sources. The browser downloads the full-size image regardless of viewport.
Prefer vw for fluid layouts: Use vw-based widths (for example, '50vw') when the image width scales with the viewport. Use px-based widths when the image has a fixed maximum size (for example, product detail at '680px').
Set width/height on non-DynamicImage <img> elements: Always include explicit width and height attributes on standard <img> elements to prevent Cumulative Layout Shift (CLS). <DynamicImage> handles this via its responsive <picture> and sizing attributes.
Use DynamicImageProvider for grids: Wrap product grids in a provider to control priority centrally rather than passing props through every tile.
Tune quality per use case: A quality of 70 is a good baseline. Hero banners or product zoom may benefit from higher values (80–85). Thumbnails and carousels can go lower (50–60). Override globally per-environment via PUBLIC__app__images__quality, or per-image by adding the q parameter to the src URL (for example, src="https://example.com/image.jpg?q=85"). A q parameter present in the src URL takes priority over the global config.
Alt Text Strategy
Providing meaningful alt text is essential for accessibility and SEO.
Source of Truth
For commerce product images, SCAPI image alt text is the source of truth.
Fallback Order
Use this fallback order for product images.
SCAPI image alt (image.alt)
Product name (productName / name)
Localized generic fallback (for example, t('common:productImageAlt'))
Non-localized English fallback as a final safety net (for example, 'Product Image')
Use explicit || fallback chains in components to preserve this order.
Rules
Always provide an alt attribute on rendered <img> elements.
Use localized strings for generic fallback alt text, then a hardcoded English fallback as the last resort.
Decorative images must set alt="" when the image is purely decorative and has no meaningful text equivalent.
j