Managing product images in specific contexts

In this guide, you will learn how to control the product images that will be displayed in your store sections by labeling them with specific contexts on VTEX Catalog. These contexts determine where the image is displayed and are defined as follows:

Gallery context: Restricts the image to display only in the Product Image Gallery, allowing you to curate a set of images highlighting key features.
SKU selector context: Restricts the image to display only in the SKU selector, providing a zoomed-in view for detailed examination.
Generic context (default): Sets the image to display in all sections.

For example, you may want to limit the number of images displayed in the Product Details Page (PDP) gallery to highlight key product features.

Before	After
${"base64":" ","img":{"width":1999,"height":990,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":209803,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/before___bec5e5c536162b228cd4d50d0042c4a6.png"}}$	${"base64":" ","img":{"width":1999,"height":918,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":185490,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/after___f6bb9be611ba511d7eee8558c34a2732.png"}}$
The product image gallery displays all five images uploaded to Catalog.	After limiting the number of images, only three product images are displayed to focus on the most important product features.

By associating images with specific contexts, you ensure only the most relevant images are in the sections.

Before you begin

To follow the instructions in this guide, you must understand the concepts of API extensions and Section override.

Instructions

For this tutorial, we will create a custom gallery for the PDP using the label feature from VTEX Catalog.

In this example, we will create a context by labeling selected images with the term gallery. This gallery will only display images that have been assigned the gallery label in Catalog.

Step 1: Labeling images in Catalog

Label your product images with the label field in Catalog. This label determines where product images should be displayed in your store. To label your images, follow these steps:

Access the VTEX Admin.
Go to Catalog > All Products and find the product you want to edit.
Click the Update button and then click SKU.

${"base64":" ","img":{"width":1588,"height":482,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":156517,"url":"https://vtexhelp.vtexassets.com/assets/docs/src/sku-images-admin___1baaa1f88be16795b892634b80676ccc.gif"}}$
Go to the SKU you want to update and click Edit.
Click the Images tab.

For each SKU image you want to add to the gallery, set the Label field to gallery. These are the available labels:

Label name	Description
`gallery`	Restricts the image to display only on the Product Image Gallery.
`generic`	Includes the image in all contexts by default. Images labeled as `generic` are always displayed as part of the complete set of images.
`skuvariation`	Assigns the image to the SKU Selector. If no image has this label, the first image of the SKU is used.

Click Save Label and Save.

Step 2: Querying images by context

Update your store ServerProduct and ClientProduct fragments to retrieve images based on their assigned labels. This ensures that only relevant images for specific contexts, like the PDP, are retrieved.

For more information about fragments in FastStore, see the guide Extending queries using fragments.

Open your store code using the code editor of your choice.
Go to src/fragments/ServerProduct.ts and add the following:

src/fragments/ServerProduct.ts
_12import { gql } from '@faststore/core/api' _12 _12export const fragment = gql` _12fragment ServerProduct on Query { _12 product(locator: $locator) { _12 galleryImages: image(context: "gallery", limit: 3) { _12 url _12 alternateName _12 } _12 } _12} _12`
Go to src/fragments/ClientProduct and add the following:

src/fragments/ClientProduct
_12import { gql } from '@faststore/core/api' _12 _12export const fragment = gql` _12fragment ClientProduct on Query { _12 product(locator: $locator) { _12 galleryImages: image(context: "gallery", limit: 3) { _12 url _12 alternateName _12 } _12 } _12} _12`

❕The limit: 3 argument selects only three images. Omitting this argument returns all images labeled gallery. By default, all images are returned if no context label is found.

Step 3: Overriding the `ImageGallery` component

Customize the default ImageGallery component to showcase the images retrieved in the previous step. This override allows you to control how images are displayed and interacted with on your PDP.

In your store code, create the ProductDetails.tsx file inside the src/components/overrides folder.
In the ProductDetails.tsx file, add the following content:

_50import { SectionOverride } from "@faststore/core"; _50 _50import { usePDP } from "@faststore/core"; _50import { Image_unstable as Image } from "@faststore/core/experimental"; _50 _50import { ImageGallery, ImageGalleryViewer } from "@faststore/ui"; _50import { useState } from "react"; _50 _50const SECTION = "ProductDetails" as const; _50 _50const ImageComponent = ({ url, alternateName }: {url: string, alternateName?: string}) => { _50return <Image src={url} alt={alternateName} width={68} height={68}/> _50} _50 _50const override: SectionOverride = { _50section: SECTION, _50components: { _50 __experimentalImageGallery: { _50 Component: () => { _50 const { data } = usePDP(); _50 const [selectedIndex, setSelectedIndex] = useState<number>(0); _50 _50 const currentImage = data.product.galleryImages[selectedIndex]; _50 _50 return ( _50 <ImageGallery _50 images={data.product.galleryImages} _50 ImageComponent={ImageComponent} _50 selectedImageIdx={selectedIndex} _50 setSelectedImageIdx={setSelectedIndex} _50 data-fs-product-details-gallery="true" _50 > _50 <ImageGalleryViewer> _50 <Image _50 sizes="(max-width: 360px) 50vw, (max-width: 768px) 90vw, 50vw" _50 width={691} _50 height={691 * (3 / 4)} _50 loading="eager" _50 src={currentImage.url} _50 alt={currentImage.alternateName} _50 /> _50 </ImageGalleryViewer> _50 </ImageGallery> _50 ); _50 }, _50 }, _50}, _50}; _50 _50export { override };
- The ServerProduct and ClientProduct fragments are accessed via the usePDP hook.
- Instead of using the images being passed to the ImageGallery component, we are using the galleryImages we defined.
Open a terminal and run yarn dev to sync the changes made in the previous steps.
Open a pull request to your store with these changes. Once the pull request is reviewed and approved, merge it into the main branch.

Considerations for SKU Selector Images

The FastStore API defines a specific name for images that are supposed to display on the SKU Selector. The first image labeled skuvariation in Catalog will automatically display on the SKU Selector. If no image has the skuvariation label, the first image of the SKU will be displayed.