Product media

Media records represent assets used by the catalog. Variants can reference media and order it for display, so two finishes of the same product can have different galleries.

Asset and association are different

Create the media record before attaching it with productVariantsMediaAdd. Reorder associations when gallery order changes. Remove an association when a variant should stop displaying an asset. Deleting the media record is a separate action that can affect other references.

For a black lamp, attach images of the black finish to that variant. When the buyer selects the white variant, switch to its media along with its price and availability. The product’s heroVariant is useful for a product-card image; it is not a guarantee that every variant has the same gallery.

Render from returned data

Use Media.src as the source URL. Do not construct CDN paths from a project name or file name. Handle a missing image with a consistent placeholder so the name, price, and purchase controls remain usable. Write alternative text that describes the product or the distinguishing detail visible in the image.

Choose image dimensions from the rendered layout and reserve the image’s aspect ratio to avoid shifting the page while it loads. See Deliver responsive product images for URL construction and a responsive component.