Product Images Block

commerce-connect/product-images

Display a product photo gallery with main image, thumbnail strip, and variant image switching.

Overview

The Product Images block shows synced product images from BigCommerce in a professional gallery layout. Customers can view the main product image, browse thumbnails, and see different images when selecting product variants.

When to Use

• Single product pages - Primary use case for product detail pages
• Product quick-view modals - Compact gallery in modal overlays
• Product comparison pages - Side-by-side product visuals

Features

• Synced from BigCommerce - Images automatically sync from BigCommerce product data
• Main image + thumbnails - Large main image with clickable thumbnail strip
• Lightbox support - Click main image to open full-screen lightbox
• Variant switching - Main image updates when customer selects product variant
• Lazy loading - Images load on demand for faster initial page load
• Responsive layout - Adapts to mobile/tablet/desktop screen sizes

Placement

• Allowed contexts: Single product pages, product templates, post content
• Ancestor constraints: None (can be placed anywhere)
• Typical locations:
  • Left column of two-column product page layout
  • Above product title on mobile layouts
  • Inside product quick-view modal

Attributes

Attribute	Type	Default	Description
layout	string	'thumbnails-below'	Thumbnail position: thumbnails-below, thumbnails-right, thumbnails-left, thumbnails-hidden
aspectRatio	string	'square'	Main image aspect ratio: square, portrait, landscape, auto
thumbnailSize	number	80	Thumbnail width/height in pixels
enableLightbox	boolean	true	Allow click to open lightbox
enableZoom	boolean	false	Enable hover-to-zoom on main image

Settings Panel

General Tab

• Layout - Choose thumbnail position relative to main image

  • Thumbnails Below (default) - Horizontal thumbnail strip below main image
  • Thumbnails Right - Vertical thumbnail strip to right of main image
  • Thumbnails Left - Vertical thumbnail strip to left of main image
  • Thumbnails Hidden - Main image only, no thumbnail navigation

• Aspect Ratio - Control main image display dimensions

  • Square (default) - 1:1 aspect ratio
  • Portrait - 3:4 aspect ratio (taller)
  • Landscape - 4:3 aspect ratio (wider)
  • Auto - Use original image aspect ratio

• Thumbnail Size - Set thumbnail dimensions (default: 80px × 80px)

• Enable Lightbox - Allow customers to click main image for full-screen view

• Enable Zoom - Enable hover-to-zoom functionality on main image (desktop only)

Style Tab

• Border Radius - Round corners of images
• Border Width - Add border around images
• Border Color - Set border color
• Spacing - Gap between main image and thumbnails
• Background Color - Background color behind images (useful for transparent PNGs)

Data Source

Images are synced from BigCommerce product data:

• Primary image - First image in BigCommerce product images array
• Additional images - All images from BigCommerce product images array
• Variant images - Variant-specific images swap in when variant selected
• Image URLs - Stored in WordPress® post meta after sync
• Alt text - Synced from BigCommerce image descriptions (SEO)

Tip

Images sync automatically via webhooks when you update product images in BigCommerce. Manual sync available at Settings → Commerce Connect → Products → Sync Products Now.

CSS Hooks

Selector	Purpose
.wp-block-commerce-connect-product-images	Root block container
.product-images__main	Main image wrapper
.product-images__main-image	Main image element
.product-images__thumbnails	Thumbnail strip container
.product-images__thumbnail	Individual thumbnail wrapper
.product-images__thumbnail-image	Thumbnail image element
.product-images__thumbnail--active	Currently selected thumbnail
.product-images__lightbox	Lightbox overlay (when enabled)

Accessibility

• ARIA labels: Main image includes aria-label="Product image" and descriptive alt text
• Keyboard navigation:
  • Arrow keys navigate between thumbnails
  • Enter/Space selects thumbnail
  • Escape closes lightbox
• Screen reader support:
  • Image count announced (“Image 1 of 5”)
  • Variant changes announced (“Image updated for selected variant”)
  • Lightbox state announced (“Lightbox opened”, “Lightbox closed”)

Examples

Example 1: Default Two-Column Layout

<!-- Product Images Block with thumbnails below (default) -->
<!-- Main image: 600x600px, Thumbnails: 80x80px, 4 product images -->

Settings:

• Layout: Thumbnails Below
• Aspect Ratio: Square
• Thumbnail Size: 80px
• Enable Lightbox: Yes

Result: Large square main image with horizontal thumbnail strip below. Click main image opens lightbox.

Example 2: Vertical Thumbnail Strip

<!-- Product Images Block with thumbnails on right side -->
<!-- Main image: 500x667px (portrait), Thumbnails: 100x100px, 6 product images -->

Settings:

• Layout: Thumbnails Right
• Aspect Ratio: Portrait
• Thumbnail Size: 100px
• Enable Zoom: Yes

Result: Portrait main image with vertical thumbnail strip on right. Hover main image triggers zoom.

Example 3: Mobile-Optimized (No Thumbnails)

<!-- Product Images Block for mobile devices -->
<!-- Main image: full width, swipe navigation, no visible thumbnails -->

Settings:

• Layout: Thumbnails Hidden
• Aspect Ratio: Auto
• Enable Lightbox: No
• Swipe gestures: Enabled (mobile only)

Result: Full-width main image. Swipe left/right to navigate images on mobile.

Customization

Via Block Settings

Use the Settings Panel in WordPress® Site Editor:

1. Select Product Images block in template editor
2. Open Settings sidebar (right panel)
3. Configure layout, aspect ratio, thumbnail size
4. Adjust spacing and styling in Style tab

Via Custom CSS

/* Customize main image border */
.wp-block-commerce-connect-product-images .product-images__main-image {
  border: 2px solid #e5e7eb;
  border-radius: 8px;
}

/* Customize thumbnail spacing */
.wp-block-commerce-connect-product-images .product-images__thumbnails {
  gap: 12px; /* Space between thumbnails */
}

/* Highlight active thumbnail */
.wp-block-commerce-connect-product-images .product-images__thumbnail--active {
  border: 2px solid #8b5cf6;
  opacity: 1;
}

Via Hooks/Filters

// Customize image size used for main image
add_filter('commerce_connect_product_image_size', function($size) {
  return 'large'; // Use WordPress® 'large' size instead of default
});

// Customize lightbox behavior
add_filter('commerce_connect_product_image_lightbox_enabled', function($enabled, $product_id) {
  // Disable lightbox for specific products
  if ($product_id === 123) {
    return false;
  }
  return $enabled;
}, 10, 2);

// Add custom image attributes
add_filter('commerce_connect_product_image_attributes', function($attributes, $product_id) {
  $attributes['loading'] = 'eager'; // Load first image immediately
  return $attributes;
}, 10, 2);

Troubleshooting

Issue: Images not loading (broken image icons)

Symptoms: Product page shows broken image icons instead of product photos

Cause: BigCommerce image URLs are 404, images didn’t sync, or CDN blocked

Solution:

1. Check image URLs in BigCommerce admin (Products → Edit Product → Images)
2. Verify images are assigned to WordPress® channel in BigCommerce
3. Trigger manual sync: Settings → Commerce Connect → Products → Sync Products Now
4. Check browser Network tab for 404 errors on image URLs
5. Verify WordPress® site can reach BigCommerce CDN (not blocked by firewall)

Issue: Thumbnails not appearing

Symptoms: Main image displays but thumbnail strip is empty

Cause: Only one product image, or thumbnails hidden in block settings

Solution:

1. Verify product has multiple images in BigCommerce (minimum 2 for thumbnails)
2. Check block settings: Layout should NOT be “Thumbnails Hidden”
3. Verify CSS isn’t hiding thumbnails (check for display: none in browser inspector)

Issue: Lightbox not working

Symptoms: Clicking main image doesn’t open lightbox

Cause: Lightbox disabled in settings, JavaScript error, or theme conflict

Solution:

1. Check block settings: “Enable Lightbox” should be checked
2. Open browser console, look for JavaScript errors
3. Test with default WordPress® theme (Twenty Twenty-Four) to rule out theme conflict
4. Clear browser cache and try again

Issue: Images don’t update when selecting variants

Symptoms: Main image stays the same when customer selects different product variant

Cause: Variants don’t have specific images assigned in BigCommerce

Solution:

1. In BigCommerce admin, edit product variants
2. Assign specific images to each variant (e.g., red shirt shows red image)
3. Sync products to WordPress®
4. Test variant selection on frontend

Related Blocks

• Product Title - Typically placed above or beside Product Images
• Product Pricing - Usually placed near Product Images on product pages
• Product Buy Button - Positioned below Product Images in typical layouts
• Single Product - Parent block that can contain Product Images + other product blocks

Related Documentation

• Product Sync - How images sync from BigCommerce
• Site Editor Guide - Using blocks to build product page templates
• Block Customization - Advanced styling and behavior
• Performance Optimization - Optimize image loading for faster pages