The properties of product images used on the Magento 2 storefront are stored in the view.xml configuration file. This topic provides all details about what properties are available and how to configure them.

The properties for the images displayed on the product pages are defined by the gallery widget options. The options of the widget can be configured in the theme view.xml as well. For detail view the Gallery widget topic.

Configure image properties in view.xml

The conventional location of view.xml for a theme is:


For example, here is the view.xml of the Magento Blank theme: app/design/frontend/Magento/blank/etc/view.xml.

In view.xml, image properties are configured in the scope of <images module="Magento_Catalog"> element:

<images module="Magento_Catalog">

Image properties are configured for each image type defined by the id and type attributes of the <image> element:

<images module="Magento_Catalog">
	<image id="unique_image_id" type="image_type">

The following table describes the attributes in detail:

idstringImage identifier. Unique in the scope of theme.

Can have any value, but in out-of-the- box Magento themes id‘s are meaningful and describe the location of an image.

For example, the id value for images of cross-sell products displayed in a shopping card is cart_cross_sell_products.

id‘s are used in .phtml templates for defining the type and properties of images displayed in each particular location on a particular page.

typestringThe type of the images defined by the specified id. Allowed values:

  • image – corresponds to the Base Image role in the Magento Admin
  • small_image – corresponds to the Small Image role in the Magento Admin
  • swatch_image – corresponds to the Swatch Image role in the Magento Admin
  • swatch_thumb – corresponds to the Swatch Image role in the Magento Admin.
  • thumbnail – corresponds to the Thumbnail Image role in the Magento Admin

The following picture illustrates how image roles for product images are specified in the Magento Admin: How to configure images properties for a Magento 2 theme?

Image properties are defined by the corresponding elements, for example:

<images module="Magento_Catalog">
    <image id="unique_image_id" type="image">
        <width>100</width> <!-- Image width in px --> 
        <height>100</height> <!-- Image height in px -->

The following table contains the list of all properties which can be configured:

widthintegerImage width in pixels.Optional
heightintegerImage height in pixels.Optional
constrainbooleanIf set to true, images that are smaller than required by the configuration, are not enlarged. Default value: true.Optional
aspect_ratiobooleanIf set to true, proportions of images are not changed even if required by the configuration. Default value:true.Optional
framebooleanIf set to true, images are not cropped. Default value: true. Applied only if aspect_ratiois set to true.Optional
transparencybooleanIf set to true, the transparent background of images is saved. If is set to false, images have the white background (by default). You can set the color for the background using thebackground parameter. Default value: true.Optional
backgroundstringThe color for the images background. Not applied to images with transparency, iftransparency is set to true. Format: “[, , ]”, e.g.: “[255, 255, 255]”.Optional

Resize catalog images

The magento catalog:images:resize command enables you to resize images for display on your storefront; for example:

  • After you import products, which might have variable sized images
  • If images were resized or deleted manually from cache

Each image assigned to a product must be resized in accordance with image metadata defined in a module’s view.xml configuration file. After resizing an image, its resized copy is stored in the cache (/pub/media/catalog/product/cache directory). Magento serves storefront images from cache.

Generally, product images are cached while saving the product. However, sometimes you might need to re-create the product images cache using this command—for example, after you import products, if images were resized manually in the cache, or if the cache was manually cleared by mistake.

Command usage:

php <magento install dir>/bin/magento catalog:images:resize

This command has no arguments or options. A progress indicator displays while the command runs.

The message Product images resized successfully displays to confirm the command succeeded.


You may also like

Leave A Comment

Please enter your name. Please enter an valid email address. Please enter message.