Documentation
Feedback
Guides
VTEX IO Apps

VTEX IO Apps
Store Components
Product Images
vtex.store-components
Version: 3.173.0
Latest version: 3.173.0

The product-images block renders 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 dependencies in the manifest.json file, as in the following example:

_10
"dependencies": {
_10
"vtex.store-components": "3.x"
_10
}

  1. Add the product-images block to any child of the store.product template (Product Details page template). For example:

_10
"store.product": {
_10
"children": [
_10
"flex-layout.row#product",
_10
]
_10
},
_10
"flex-layout.row#product": {
_10
"children": [
_10
+ "product-images"
_10
]
_10
},

  1. Then, declare the product-images block using the props stated in the Props table. For example:

_10
"product-images": {
_10
"props": {
_10
"displayThumbnailsArrows": true
_10
}
_10
},

Props

Prop nameTypeDescriptionDefault value
aspectRatiostringSets the aspect ratio of the image; 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 thumbnail 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 with the product-summary-sku-selector block. To learn more, please read the SKU Selector documentation.skuvariation
maxHeightnumberMaximum height for individual product images (in pixels).600
ModalZoomblockOpens a modal for product image zooming. This prop 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). Please note that the ModalZoom prop will only work if the zoomMode prop is set as open-modal. To learn more, please see the Advanced Configuration section.undefined
placeholderstringSets the URL for a placeholder image to be used if there is no available image or video of the product.undefined
positionenumSets the position of the thumbnails (left or right). Only used when thumbnailsOrientation is verticalleft
showNavigationArrowsbooleanDefines if the navigation arrows should be displayed.true
showPaginationDotsbooleanDefines if the pagination dots should be displayed.
showImageLabelbooleanControls if the image label text should be rendered above each imagetrue
thumbnailVisibilityvisible or hiddenDefines if the thumbnails should be displayed in carousel displayMode.visible
thumbnailAspectRatiostringSets the aspect ratio of the thumbnail image. For more information about aspect ratio, check out the aspectRatio prop"auto"
thumbnailMaxHeightnumberMaximum height of the thumbnail image (in pixels).150
thumbnailsOrientationenumDefines the orientation of the thumbnails. It can be vertical or horizontal.vertical
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 is triggered when the image is clicked), in-place-hover (zoom is triggered when the image is hovered on), and open-modal (image is zoomed using a modal).in-place-click

Advanced configuration

In this section, you will learn how to use modal zoom, a property for when you want to open a popup containing a 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 explained, the zoomMode prop allows the trigger of a modal for image zooming. In addition to that, the MozalZoom prop will render the block defined as its value. In this case, the modal-layout is required. This way, you will be 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 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.

For example:


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

Please note that the product-images.high-quality-image block must be declared as a child of modal-layout. 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
aspectRatiostringDefines the aspect ratio of the image; 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 srcset HTML attribute. If no value is defined for this prop, the srcset will use the original image size.undefined
maxSizenumberImage maximum size (in px) for rendering, regardless of the screen size. Please note that this prop only works if you also declare the imageSizes prop.4096
zoomFactornumberDefines 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 is triggered when the image is clicked), and in-place-hover (zoom is triggered when the image is hovered on). Unlike the store-images prop, this one does not accept the open-modal value.disabled

Customization

To apply CSS customizations to this and other blocks, please see 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
productImageLabel
productVideo
swiper-pagination
swiperBullet--active
swiperBullet
swiperCaret
swiperCaretNext
swiperCaretPrev
thumbImg
thumbImg--video
video
video
videoContainer
See also
Vtex.store Components
VTEX IO Apps
VTEX App Store
VTEX IO Apps