Documentation
Feedback
Guides
VTEX IO Apps

VTEX IO Apps
Store Components
Product Images

The product-images block is responsible for rendering a product image or video.

{"base64":"  ","img":{"width":2102,"height":1084,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":409582,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-store-components-productimages-0.png"}}

Configuration

  1. Import the vtex.store-components app to your theme's dependencies in the manifest.json file as in the following example:
"dependencies": { "vtex.store-components": "3.x" }
  1. Add the product-images block to any child of the store.product template (Product Details Page template). For example:
"store.product": { "children": [ "flex-layout.row#product", ] }, "flex-layout.row#product": { "children": [ + "product-images" ] },
  1. Then, declare the product-images block using the props stated in the Props table. For example:
"product-images": { "props": { "displayThumbnailsArrows": true } },

Props

Prop nameTypeDescriptionDefault Value
aspectRatiostringSets the aspect ratio of the image, that is, whether the image should be square, portrait, landscape, etc. The value should follow the common aspect ratio notation i.e. two numbers separated by a colon such as 1:1 for square, 3:4 for upright portrait, or 1920:1080 for even large values)"auto"
contentOrder'videos-first' | 'images-first'Controls the order in which the images and videos are displayed.'images-first'
contentTypeenumControls the type of content that will be displayed in the block. Possible values are: images, videos, or all.all
displayModeenumDefines how the product media should be displayed. Possible values are carousel (displays the product images and videos in a carousel), list (displays only the product images inline, with no extra markup) and first-image (displays only the first image available). Caution: The list and first-image values do not display product videos and are only compatible with the maxHeight, hiddenImages, zoomFactor, aspectRatio,ModalZoomElement, and zoomMode props.carousel
displayThumbnailsArrowsbooleanDisplays navigation arrows on the thumbnails media (if there are enough thumbnails for them to scroll)false
hiddenImagesstringHides images whose labels match the values listed in this prop. Intended to be used along with the product-summary-sku-selector block. You can have more information at the SKU Selector documentationskuvariation
maxHeightnumberMaximum height for individual product images (in pixels).600
ModalZoomblockOpens a modal for product image zooming. This prop's value must match the name of the block responsible for triggering the modal containing the product image for zooming (e.g. modal-layout from Modal layout app). Notice that the ModalZoom prop will work only if the zoomMode prop is set as open-modal. To learn more, check out the Advanced Configuration section.undefined
placeholderstringSets the URL for a placeholder image to be used in case there is no available image or video of the product.undefined
positionEnumSet the position of the thumbnails (left or right). Only used when thumbnailsOrientation is verticalleft
showNavigationArrowsbooleanControls if the navigation arrows should appeartrue
showPaginationDotsbooleanControls if the pagination dots should appeartrue
thumbnailVisibilityvisible or hiddenControls if the thumbnails should appear in carousel displayModevisible
thumbnailAspectRatiostringSets the aspect ratio of the thumbnail image; For more information about aspect ratio, check the aspectRatio prop"auto"
thumbnailMaxHeightnumberMaximum height for the thumbnail image (in pixels).150
thumbnailsOrientationEnumChoose the orientation of the thumbnails. Can be set to vertical or horizontalvertical
zoomFactornumberSets how much the zoom increases the image size (e.g. 2 will make the zoomed-in image twice as large)2
zoomModeenumDefines the image zoom behavior. Possible values are: disabled (zoom is disabled), in-place-click(zoom will be triggered when the image is clicked on), in-place-hover(zoom will be triggered when the image is hovered on) or open-modal (image is zoommed using a modal).in-place-click

Advanced configuration

In this section, we teach you how to use modal zoom, a property for when you want to open a popup containing the product image for zooming. To use this feature, configure your product-images block using the zoomMode and ModalZoom props with open-modal and modal-layout set as its values, respectively.

When configured as stated previously, the zoomMode prop will allow the trigger of a modal for image zooming. In addition to that, the MozalZoom prop will render the block passed in as its value - in this case, mandatorily the modal-layout. In such a way, we become able to configure a modal containing the product image for zooming.

Once both props are correctly configured, you must declare the modal-layout block and the product-images.high-quality-image block as its child.

The modal-layout block is the one responsible for building the Modal component and triggering the image zooming in a popup box. The product-images.high-quality-image block, in turn, is a special block, only meant to render the product-image block inside the modal.

Check out the following example:

{ "product-images.high-quality-image": { "props": { "zoomMode": "in-place-click", "zoomFactor": 2 } }, "modal-layout#product-zoom": { "children": [ // you can put any other block inside the modal, // this is just a normal modal "flex-layout.row#product-name", "product-images.high-quality-image" ] }, "product-images": { "props": { "ModalZoom": "modal-layout#product-zoom", // to use the ModalZoom, the product-images zoomMode value must be set as open-modal "zoomMode": "open-modal", "aspectRatio": { "desktop": "auto", "phone": "16:9" } } } }

Notice that the product-images.high-quality-image block must be declared as a child of modal-layout and, in addition to that, you can also declare other blocks exported by the Modal Layout app as children.

The following table shows the props allowed by product-images.high-quality-image:

Prop nameTypeDescriptionDefault Value
aspectRatiostringSets the aspect ratio of the image, that is, whether the image should be square, portrait, landscape, etc. The value should follow the [common aspect ratio notation](https://en.wikipedia.org/wiki/Aspect_ratio_(image) i.e. two numbers separated by a colon such as 1:1 for square, 3:4 for upright portrait, or 1920:1080 for even large values).auto
defaultSizenumberImage default size (in px).1200
imageSizes[number]Image size(s) (in px) to be used in the image's srcset HTML attribute. If no value is passed to this prop, the srcset will use the image original size.undefined
maxSizenumberImage maximum size (in px) for rendering regardless of the screen size. Notice that this prop only works if you also declare the imageSizes prop.4096
zoomFactornumberSets how much the zoom increases the image size (e.g. 2 will make the zoomed-in image twice as large).2
zoomModeenumDefines the zoom behavior for the product-images.high-quality-image block. Possible values are: disabled (zoom is disabled), in-place-click(zoom will be triggered when the image is clicked on), or in-place-hover(zoom will be triggered when the image is hovered on). Different from the store-images prop, this one doesn't accept open-modal value.disabled

Customization

To apply CSS customizations in this and other blocks, follow the Using CSS handles for store customization guide.

CSS Handles
carouselContainer
carouselCursorDefault
carouselGaleryCursor
carouselGaleryThumbs
carouselIconCaretLeft
carouselIconCaretRight
carouselImagePlaceholder
carouselInconCaretRight
carouselThumbBorder
figure
figure--video
highQualityContainer
image
imgZoom
productImagesContainer (content is deprecated)
productImagesContainer--carousel
productImagesContainer--list
productImagesGallerySlide
productImagesGallerySwiperContainer
productImagesThumb
productImagesThumbActive
productImagesThumbCaret
productImagesThumbsSwiperContainer
productImageTag--main
productImageTag--zoon
productImageTag
productVideo
swiper-pagination
swiperBullet--active
swiperBullet
swiperCaret
swiperCaretNext
swiperCaretPrev
thumbImg
thumbImg--video
video
video
videoContainer
Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Product Description
« Previous
Product Name
Next »
Contributors
2
Photo of the contributor
Photo of the contributor
+ 2 contributors
On this page