Set product image widths in a WooCommerce theme

Set the image widths your WooCommerce theme requests for catalog thumbnails, gallery thumbnails, and the main product image. The example preserves other WooCommerce theme settings.

Before you start

↑ Back to top

• A staging site with a backup and a way to restore theme files if PHP fails.
• An active child theme, or a theme you maintain, and access to its functions.php file. Do not edit WooCommerce or a third-party parent theme.
• A classic theme that already declares WooCommerce support. See the classic theme developer handbook for theme integration.
• A product with a featured image and at least two gallery images for testing.

These settings define requested image sizes in pixels. Your theme’s CSS still controls the displayed width. Use original images large enough for the sizes you choose; requesting a larger size cannot add detail to a smaller original.

Set the requested widths

↑ Back to top

1. Choose widths that fit your theme’s catalog cards, gallery thumbnails, and main product image. The values below are examples.
2. In your theme’s functions.php, add the following callback inside its existing PHP section. Replace 300, 100, and 800 with your chosen widths. Do not add a second PHP opening tag.
3. Save the file. The callback runs after theme setup callbacks using the default priority; if your parent theme replaces WooCommerce support later, run it after that callback.

/**
 * Set product image widths while preserving other WooCommerce theme settings.
 */
function mytheme_set_product_image_widths() {
	$support  = get_theme_support( 'woocommerce' );
	$settings = is_array( $support ) && isset( $support[0] ) && is_array( $support[0] ) ? $support[0] : array();

	$settings['thumbnail_image_width']         = 300;
	$settings['gallery_thumbnail_image_width'] = 100;
	$settings['single_image_width']            = 800;

	add_theme_support( 'woocommerce', $settings );
}
add_action( 'after_setup_theme', 'mytheme_set_product_image_widths', 100 );

The callback keeps existing WooCommerce support settings, such as product_grid, and replaces only the three image-width values. It assumes your theme already integrates with WooCommerce.

• thumbnail_image_width: catalog image width. The catalog cropping setting controls its aspect ratio.
• gallery_thumbnail_image_width: square thumbnail width below the classic product image.
• single_image_width: main product image width, without cropping.

When the theme declares catalog or main-image widths, WooCommerce hides the corresponding width controls in Appearance > Customize > WooCommerce > Product Images. The theme values take precedence over those saved width settings.

Verify the image sizes

↑ Back to top

1. Upload a new test image with dimensions larger than your requested widths and assign it to the test product. This avoids confusing an old generated image with the new settings.
2. Open the catalog and product page on desktop and a narrow screen. Check image sharpness, cropping, gallery thumbnails, and variation images.
3. Use your browser’s developer tools to inspect the image’s source and responsive image candidates. Confirm suitable generated sizes are available; the browser may select a different candidate based on screen density and layout.
4. If existing images still use old sizes, regenerate their thumbnails with your site’s supported image-regeneration tool after taking a backup. Clear image and page caches, then check again.

If images still look wrong

↑ Back to top

If an image is blurry, check the original upload’s dimensions and the size the browser selected. If its displayed width has not changed, check the theme’s CSS; changing requested image widths does not change the page layout. A gallery replacement or an image-size filter can request different sizes.

To undo the customization, remove this callback and its add_action() line, restore the previous theme values, and regenerate affected thumbnails if needed. Keep the original uploads so image files can be regenerated.

For merchant image settings, see Adding Product Images and Galleries. For broader theme integration, see the classic theme developer handbook.