Products Pagination Block

Navigation controls for browsing through multiple pages of product results.

What It Does

The Products Pagination block adds page numbers and previous/next buttons to navigate through large product listings. It automatically appears when there are more products than the per-page limit.

Use cases:

• Product listing pages
• Search results with many matches
• Collection pages with large catalogs
• Shop pages

How to Add It

Requirements: Must be used inside a Products block.

1. Add a Products block to your page
2. Click + inside the Products block
3. Search for “Products Pagination” or look in the Commerce category
4. Click to insert

Block Settings

Display Options

Pagination style:

• Numbers - Page numbers with prev/next (default)
• Prev/Next only - Just arrow buttons
• Load More button - Ajax load more products
• Infinite scroll - Auto-load on scroll

Show/hide:

• First page button
• Last page button
• Previous button
• Next button
• Page numbers
• Dots for skipped pages (e.g., “1 2 3 … 10”)

Number Display

Page numbers shown:

• 3 (compact - shows 1 2 3 … 10)
• 5 (default - shows 1 2 3 4 5 … 10)
• 7 (expanded - shows 1 2 3 4 5 6 7 … 10)
• All (shows every page number)

Positioning

Dropzone: Place in specific layout positions:

• Below products (default)
• Above products
• Both above and below

Alignment

• Left
• Center (default)
• Right

Customization

Styling Pagination

/* Pagination container */
.wpe-commerce-products-pagination {
  display: flex;
  justify-content: center;
  gap: 0.5rem;
  margin: 2rem 0;
}

/* Page number buttons */
.wpe-commerce-products-pagination button,
.wpe-commerce-products-pagination a {
  padding: 0.5rem 0.75rem;
  border: 1px solid #ddd;
  border-radius: 4px;
  background: white;
  color: #333;
  text-decoration: none;
  cursor: pointer;
}

/* Hover state */
.wpe-commerce-products-pagination button:hover {
  background: #f5f5f5;
  border-color: #0073aa;
}

/* Active/current page */
.wpe-commerce-products-pagination .active {
  background: #0073aa;
  color: white;
  border-color: #0073aa;
  font-weight: 600;
}

/* Disabled state */
.wpe-commerce-products-pagination button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

/* Dots for skipped pages */
.wpe-commerce-products-pagination .dots {
  padding: 0.5rem;
  color: #999;
}

Mobile Responsive

/* Compact pagination on mobile */
@media (max-width: 768px) {
  .wpe-commerce-products-pagination {
    gap: 0.25rem;
  }

  /* Hide page numbers, show only prev/next */
  .wpe-commerce-products-pagination .page-number {
    display: none;
  }

  .wpe-commerce-products-pagination .prev,
  .wpe-commerce-products-pagination .next,
  .wpe-commerce-products-pagination .active {
    display: inline-block;
  }
}

Load More Button Style

/* Load More button */
.wpe-commerce-products-pagination .load-more {
  padding: 1rem 2rem;
  background: #0073aa;
  color: white;
  border: none;
  border-radius: 4px;
  font-size: 1rem;
  font-weight: 600;
  cursor: pointer;
  transition: background 0.2s;
}

.wpe-commerce-products-pagination .load-more:hover {
  background: #005a87;
}

/* Loading state */
.wpe-commerce-products-pagination .load-more.loading {
  opacity: 0.6;
  cursor: wait;
}

Common Patterns

Standard Numbered Pagination

Below products, centered:

• Style: Numbers with prev/next
• Page numbers shown: 5
• Position: Below products
• Alignment: Center

Compact Mobile Pagination

Prev/next only on small screens:

• Show: Previous, Next, Current page only
• Hide: All other page numbers
• Alignment: Center

Load More Pattern

For infinite scroll experience:

• Style: Load More button
• Position: Below products
• Shows: “Load More Products” or “Loading…”

Dual Pagination

Above and below products:

• Add two pagination blocks
• One dropzone: Above products
• One dropzone: Below products
• Same settings on both for consistency

How It Works

Page Calculation

Total products: 48
Per page: 12
Total pages: 48 ÷ 12 = 4 pages

Page 1: Products 1-12
Page 2: Products 13-24
Page 3: Products 25-36
Page 4: Products 37-48

URL Parameters

Pagination updates URL for bookmarkability:

/shop/                    # Page 1 (default)
/shop/?page=2             # Page 2
/shop/?page=3&sort=price  # Page 3 with sorting

State Preservation

When paginating:

• Current filters are preserved
• Current sort order is preserved
• Search query is preserved
• Only page number changes

Load More Behavior

Load More button:

1. Click “Load More”
2. JavaScript fetches next page via GraphQL
3. New products append to existing grid
4. Button updates to show next page available
5. When last page reached, button hides

Infinite scroll:

1. User scrolls to bottom of products
2. Intersection Observer detects viewport position
3. Automatically fetches next page
4. Appends products seamlessly
5. Continues until all pages loaded

Block Context

Must be used inside:

• Products block

Does not receive props from Products but shares parent state for:

• Total product count
• Current page
• Per-page limit
• Filters/sort applied

Does not work:

• Standalone (requires parent Products block)
• Inside Single Product block
• Outside Products block

Technical Details

Block name: wpe-commerce/products-pagination

Attributes:

• dropzone (string) - Layout position
• settingsId (string) - Settings reference
• style (string) - Pagination style (numbers, prevnext, loadmore, infinite)
• numbersShown (number) - How many page numbers to display

Supports:

• Alignment
• Custom CSS classes
• Multiple instances (for above + below placement)

Does not support:

• Typography controls
• Color controls (use CSS)
• Background controls

Troubleshooting

Pagination not showing

Check:

1. Enough products to require pagination (more than per-page limit)
2. Block is inside Products block
3. Products block has products loaded
4. Per-page setting is configured

Fix:

• If you have 12 products and per-page is 12: No pagination needed (only 1 page)
• If you have 50 products and per-page is 12: Pagination should show (5 pages)

Page numbers incorrect

Check:

1. Products block per-page setting
2. Total product count
3. Filters applied (may reduce total)

Debug calculation:

Total products shown: [X]
Per page setting: [Y]
Expected pages: [X ÷ Y] (rounded up)

Load More not loading

Check:

1. Browser console for JavaScript errors
2. Network tab for failed GraphQL requests
3. BigCommerce API connection
4. Rate limiting (too many requests)

Fix:

• Hard refresh page
• Check if Products block is fetching data
• Verify JavaScript is not blocked
• Look for console errors

URL not updating

Check:

1. JavaScript enabled
2. Browser history API supported
3. No conflicting scripts

Expected behavior:

• URL should update: /shop/?page=2
• Browser back button should work
• Bookmarking should preserve page

Infinite scroll not triggering

Check:

1. Intersection Observer supported (modern browsers)
2. Products grid has enough height to scroll
3. Scroll container is correct
4. No JavaScript errors

Fix:

// Check if Intersection Observer exists
if ('IntersectionObserver' in window) {
  console.log('Infinite scroll supported');
} else {
  console.log('Infinite scroll not supported - use Load More instead');
}

Related Blocks

• Products - Parent container block
• Products Grid - Display paginated products
• Products Counter - Show “Showing X-Y of Z”
• Products Per Page - Control items per page