A simple, powerful and independent e-commerce platform.
Sell anything with ease.

Image Sizes for Theme Developers

To display images in your catalog, Classic Commerce registers a few image sizes which define the actual image dimensions to be used. These sizes include:

woocommerce_single – This is used on the single product page. It shows the full product image, as uploaded, so is always uncropped by default. It defaults to 600px width.

woocommerce_gallery_thumbnail – This is used below the main image on the single product page to switch the gallery images. It is always square cropped and defaults to 100×100 pixels. This is used for navigating images in the gallery.

woocommerce_thumbnail  – This is used in the product ‘grids’ in places such as the shop page. It defaults to 600px width, square cropped so the product grids look neat. The aspect ratio for cropping can be customized by the store owner.

It is important to note that despite the actual image widths that are set, themes can ultimately change the size images are displayed using CSS, and image widths may be limited by the product grid/column widths.

Themes Defining Image Sizes

Themes can declare what sizes should be used when declaring Classic Commerce support. If a theme defines the image sizes (widths), the store owner will not be able to change them, but the size defined should be optimal for the theme.

add_theme_support( 'woocommerce', array(
'thumbnail_image_width' => 200,
'gallery_thumbnail_image_width' => 100,
'single_image_width' => 500,
) );

When calling ClassicPress functions which expect an image size e.g. wp_get_attachment_image_src, you should use the image size names — these are:

  • woocommerce_thumbnail
  • woocommerce_single
  • woocommerce_gallery_thumbnail

Store owners will still be able to control aspect ratio and cropping by using the customizer.

Customising Image Sizes in the Customizer

The customizer houses the options which control thumbnails in Classic Commerce.

If the theme is declaring image sizes, the top section will be hidden and only the cropping option will be visible.

Changing the cropping option, or widths, will update the preview on the right side to show how things will look. However, changes will not be visible to customers until the customizer is ‘published’ and the thumbnails have been regenerated to the new dimensions.

The thumbnail cropping section in the customizer allows store owners to select one of three cropping ratio settings for images in the catalog:

  • 1:1 (Square cropping)
  • Custom (Store owner can enter a custom aspect ratio)
  • Uncropped (Preserve single image aspect ratio)

Actual image dimensions are then calculated based on the cropping option selected, and the image width.

Changing Image Sizes via Hooks

Whilst themes can fix image sizes at certain widths, and store owners can control widths and aspect ratios, if you need more control over thumbnail sizes there are some hooks available to you.

The wc_get_image_size function is used by Classic Commerce to get the image size dimensions. The return value of this is passed through a filter:


If using this hook you’ll be passed an array of sizes, similar to this:

'width' => 200,
'height' => 200,
'crop' => 1,

So for example, if I wanted to change gallery thumbnails to be 150x150px uncropped images, you could use the following code:

add_filter( 'woocommerce_get_image_size_gallery_thumbnail', function( $size ) {
return array(
'width' => 150,
'height' => 150,
'crop' => 0,
} );

We don’t recommend plugins and themes go this route because it removes control from the store owner and their settings won’t be respected, but the option is there for store owners.

Note: after making changes to image sizes you may need to regenerate your thumbnails so the new sizes are used for existing images.

Changing Image Sizes in Classic Commerce via Hooks

As well as the above hook, some template functions in Classic Commerce run the image size through a filter so you can use something other than the Classic Commerce registered image sizes.

The following filters exist:

single_product_archive_thumbnail_size Controls the size used in the product grid/catalog. woocommerce_thumbnail
subcategory_archive_thumbnail_size Controls the size used in the product grid/catalog for category images. woocommerce_thumbnail
woocommerce_gallery_thumbnail_size Controls the size used in the product gallery, below to main image, to switch to a different image. Array representing the dimensions of the gallery_thumbnail image size. Usually array( 100, 100 ).
woocommerce_gallery_image_size Controls the size used in the product gallery. woocommerce_single
woocommerce_gallery_full_size Controls the size used in the product gallery to zoom or view the full size image. full

Note: full is a size registered by ClassicPress and set in Settings > Media.

As an example, let’s say I wanted to make the gallery thumbnail size used the thumbnail size registered by ClassicPress instead of woocommerce_gallery_thumbnail. The following snippet would do the job:

add_filter( 'woocommerce_gallery_thumbnail_size', function( $size ) {
return 'thumbnail';
} );

Note: The hooks listed above are used by Classic Commerce core. If a theme has custom template files or uses it’s own functions to output images, these filters may not be in use.