Products Grid Block

commerce-connect/products-grid

Display products in a responsive grid layout with configurable columns, pagination, and filtering.

Overview

The Products Grid block is the primary way to display product collections on your storefront. It shows products in a clean grid layout with product cards (image, title, price, rating) and supports filtering, sorting, and pagination.

When to Use

• Shop pages - Main product catalog page
• Category pages - Products filtered by category
• Search results - Products matching search query
• Featured collections - Curated product sets on homepage
• Sale pages - Discounted products collection

Features

• Responsive grid - Adapts from 1 column (mobile) to 6 columns (desktop)
• Configurable layout - Control columns, gap, product card contents
• Pagination - Load more button or numbered pagination
• Filtering - Works with Products Filters block for dynamic filtering
• Sorting - Integrates with Products Sort Control block
• Real-time updates - Syncs with BigCommerce product changes via webhooks

Placement

• Allowed contexts: Any page or template
• Ancestor constraints: Typically inside commerce-connect/products parent block
• Typical locations:
  • Main content area of shop page
  • Below category description on category pages
  • Search results page
  • Homepage featured products section

Attributes

Attribute	Type	Default	Description
columns	number	3	Number of columns on desktop (1-6)
columnsTablet	number	2	Number of columns on tablet
columnsMobile	number	1	Number of columns on mobile
gap	string	'medium'	Space between product cards: small, medium, large
productsPerPage	number	12	Number of products to display per page
paginationType	string	'numbered'	Pagination style: numbered, load-more, infinite-scroll
showImage	boolean	true	Display product image on card
showTitle	boolean	true	Display product title on card
showPrice	boolean	true	Display product price on card
showRating	boolean	true	Display star rating on card
showAddToCart	boolean	false	Display “Add to Cart” button on card

Settings Panel

General Tab

• Columns (Desktop) - Number of product columns on desktop screens (1-6, default: 3)
• Columns (Tablet) - Number of product columns on tablet screens (1-4, default: 2)
• Columns (Mobile) - Number of product columns on mobile screens (1-2, default: 1)
• Products Per Page - How many products to show per page (default: 12)
  • Overrides global setting from Settings → Commerce Connect → Products
• Pagination Type
  • Numbered (default) - Page numbers (1, 2, 3…)
  • Load More - “Load More Products” button
  • Infinite Scroll - Auto-load as user scrolls

Product Card Settings

Control what information appears on each product card:

• Show Image - Display product thumbnail (default: on)
• Show Title - Display product name (default: on)
• Show Price - Display product price (default: on)
• Show Rating - Display star rating + count (default: on)
• Show Add to Cart - Display “Add to Cart” button on card (default: off)
  • Note: Adds bulk to cards; typically used for simple products only

Style Tab

• Gap - Space between product cards (small: 16px, medium: 24px, large: 32px)
• Card Border - Add border around product cards
• Card Border Radius - Round corners of product cards
• Card Padding - Internal padding within product cards
• Card Background - Background color of product cards
• Card Hover Effect - Shadow or lift effect on hover

Data Source

Products are queried from WordPress® post type product, which contains synced data from BigCommerce:

• Query filters - Category, brand, price range, attributes (when used with Products Filters block)
• Sort order - Controlled by Products Sort Control block or global default
• Pagination - Managed by block attributes and URL parameters
• Real-time sync - Products update when BigCommerce webhooks fire

Note

The Products Grid displays products assigned to the WordPress® channel in BigCommerce. Products not assigned to this channel won’t appear.

CSS Hooks

Selector	Purpose
.wp-block-commerce-connect-products-grid	Root grid container
.products-grid__container	Inner grid wrapper
.products-grid__item	Individual product card wrapper
.product-card	Product card component
.product-card__image	Product image area
.product-card__title	Product title text
.product-card__price	Product price display
.product-card__rating	Star rating component
.product-card__add-to-cart	Add to cart button
.products-grid__pagination	Pagination controls

Accessibility

• ARIA labels: Grid has role="list", cards have role="listitem"
• Keyboard navigation:
  • Tab navigates through product cards
  • Enter/Space activates product link or add to cart
  • Arrow keys navigate pagination (numbered type)
• Screen reader support:
  • Product count announced (“Showing 12 of 48 products”)
  • Page changes announced (“Page 2 of 4”)
  • Filter changes announced (“Filtered by Category: Electronics”)
• Focus management: Focus returns to grid after pagination click

Examples

Example 1: Default Shop Page Grid

<!-- Products Grid Block (3 columns, 12 per page) -->
<!-- Settings: Default configuration -->

Settings:

• Columns: 3 (desktop), 2 (tablet), 1 (mobile)
• Products Per Page: 12
• Pagination: Numbered
• Show: Image, Title, Price, Rating
• Gap: Medium

Result: Classic 3-column product grid with numbered pagination at bottom.

Example 2: Featured Products (Homepage)

<!-- Products Grid Block (4 columns, 8 products, no pagination) -->
<!-- Curated collection for homepage hero -->

Settings:

• Columns: 4 (desktop), 2 (tablet), 1 (mobile)
• Products Per Page: 8
• Pagination: None (disable pagination to show fixed set)
• Show: Image, Title, Price
• Gap: Large
• Card Hover Effect: Lift

Result: Eye-catching 4-column grid showcasing featured products, no pagination.

Example 3: Mobile-Optimized List View

<!-- Products Grid Block (1 column, large cards) -->
<!-- Optimized for mobile shopping -->

Settings:

• Columns: 1 (all devices)
• Products Per Page: 10
• Pagination: Load More
• Show: Image, Title, Price, Rating, Add to Cart
• Gap: Medium
• Card Padding: Large

Result: Full-width product cards with all info visible, “Load More” button at bottom.

Example 4: Sale Page with Filters

<!-- Products Grid Block (3 columns) -->
<!-- Used with Products Filters block for dynamic filtering -->

Settings:

• Columns: 3 (desktop), 2 (tablet), 1 (mobile)
• Products Per Page: 24 (more products for sale browse)
• Pagination: Infinite Scroll
• Show: Image, Title, Price (with sale price strikethrough)
• Gap: Small (fit more products on screen)

Result: Filtered product grid with infinite scroll, works with sidebar filters.

Customization

Via Block Settings

1. Select Products Grid block in Site Editor
2. Open Settings panel (right sidebar)
3. Adjust columns, products per page, pagination type
4. Configure product card display options
5. Style in Style tab (gap, borders, colors)

Via Custom CSS

/* Customize product card appearance */
.wp-block-commerce-connect-products-grid .product-card {
  border: 1px solid #e5e7eb;
  border-radius: 12px;
  transition: all 0.3s ease;
}

/* Hover effect on product cards */
.wp-block-commerce-connect-products-grid .product-card:hover {
  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
  transform: translateY(-4px);
}

/* Customize product title styling */
.wp-block-commerce-connect-products-grid .product-card__title {
  font-size: 18px;
  font-weight: 600;
  color: #1f2937;
}

/* Customize price display */
.wp-block-commerce-connect-products-grid .product-card__price {
  font-size: 20px;
  font-weight: 700;
  color: #8b5cf6;
}

/* Sale price styling */
.wp-block-commerce-connect-products-grid .product-card__price--sale {
  color: #ef4444;
}

.wp-block-commerce-connect-products-grid .product-card__price--compare {
  text-decoration: line-through;
  color: #9ca3af;
  font-size: 16px;
}

Via Hooks/Filters

// Customize products per page globally
add_filter('commerce_connect_products_per_page', function($per_page) {
  return 24; // Override default to 24 products per page
});

// Customize product query (e.g., exclude specific products)
add_filter('commerce_connect_products_query', function($query_args) {
  $query_args['post__not_in'] = [123, 456]; // Exclude products by ID
  return $query_args;
});

// Customize product card HTML
add_filter('commerce_connect_product_card_html', function($html, $product_id) {
  // Add custom badge to featured products
  if (get_post_meta($product_id, '_featured', true)) {
    $html = '<div class="badge badge-featured">Featured</div>' . $html;
  }
  return $html;
}, 10, 2);

// Customize pagination HTML
add_filter('commerce_connect_products_pagination', function($pagination_html, $total_pages, $current_page) {
  // Custom pagination styling or structure
  return $pagination_html;
}, 10, 3);

Troubleshooting

Issue: Products not appearing

Symptoms: Empty grid, “No products found” message, or blank space

Cause: Products not synced, not assigned to channel, or query filters too restrictive

Solution:

1. Verify products synced: Settings → Commerce Connect → Products (check count)
2. Trigger manual sync: Sync Products Now button
3. Check products assigned to WordPress® channel in BigCommerce admin
4. Review filter settings (if using Products Filters block)
5. Check WordPress® error log for sync failures

Issue: Grid layout broken (products stacked or overlapping)

Symptoms: Products appear in single column on desktop, or overlap each other

Cause: CSS conflicts with theme, incorrect column settings, or cache issue

Solution:

1. Check column settings in block (should be 3+ for desktop)
2. Clear browser cache and WordPress® object cache
3. Test with default theme (Twenty Twenty-Four) to isolate theme conflict
4. Inspect CSS in browser dev tools (look for conflicting grid styles)
5. Ensure theme doesn’t override .products-grid__container display property

Issue: Pagination not working

Symptoms: Clicking page numbers doesn’t change products, or page reloads without updating

Cause: JavaScript error, permalink settings, or AJAX conflict

Solution:

1. Check browser console for JavaScript errors
2. Verify WordPress® permalinks set to “Post name” (not “Plain”)
3. Clear browser cache and try again
4. Test with default WordPress® theme to rule out theme conflict
5. Check for plugin conflicts (deactivate other plugins temporarily)

Issue: Product prices or images incorrect

Symptoms: Prices don’t match BigCommerce, images show wrong product

Cause: Stale sync data, webhook delivery failure, or cache issue

Solution:

1. Trigger manual sync: Settings → Commerce Connect → Products → Sync Products Now
2. Check webhook status: Settings → Commerce Connect → Data tab (see webhook troubleshooting for detailed steps)
3. Clear WordPress® object cache and Edge Full Page Cache (WP Engine)
4. Verify product data in BigCommerce admin matches expected values

Performance Optimization

Reduce Products Per Page

Showing fewer products per page improves initial load time:

// In theme functions.php
add_filter('commerce_connect_products_per_page', function() {
  return 12; // Reduce from default 24 to 12
});

Enable Object Cache

Use Redis or Memcached to cache product queries:

# Verify cache active
wp cache info

# Flush cache after bulk product updates
wp cache flush

Optimize Images

Ensure product images are optimized for web:

1. Use WebP format where supported (modern browsers)
2. Compress images before uploading to BigCommerce
3. Enable lazy loading (built-in to Products Grid)
4. Use CDN for image delivery (BigCommerce provides CDN)

Edge Full Page Cache

On WP Engine, product grids are cached at the edge for lightning-fast delivery:

• Automatic cache invalidation - Webhook sync clears cache when products updated
• Anonymous user caching - Product grids cached for non-logged-in visitors
• Configurable TTL - Default 1 hour cache lifetime

Related Blocks

• Products - Parent container block that often contains Products Grid
• Products Filters - Sidebar filters that work with Products Grid
• Products Sort Control - Dropdown to sort products in grid
• Products Count - Display “Showing X of Y products” above grid
• Products Filter Selections - Show active filters as chips above grid

Related Documentation

• Products Block - Parent container for Products Grid
• Product Sync - How products sync from BigCommerce
• Site Editor Guide - Building shop page templates
• Performance Optimization - Speed up product grid loading