Products Filters

Overview

Displays filtering controls for product collections, allowing customers to filter by category, product attributes (like size, color), and other product variations. Filters dynamically update based on the current product set and selected category or search query.

Requirements

• Parent block: Must be inside commerce-connect/products
• BigCommerce data: Product categories and variation attributes

Configuration

Attributes

• settingsId (string) - Settings configuration identifier
  • Default: ""
• dropzone (string) - Dropzone identifier for block placement
  • Default: ""

Block Support

• HTML editing: Not supported
• Multiple instances: Supported (can have multiple filter blocks)
• Alignment: Supported

Usage

Placement

This block must be placed inside the Products block. It cannot be used outside of this context. Typically placed above or beside the product grid.

Common Patterns

From the demo video script, filters are part of the complete product browsing experience:

[Products Block]
  Products Search Box
  → Products Filters ← (Category, Size, Color, etc.)
    Category: Clothing | Home Goods | Accessories
    Size: Small | Medium | Large
    Color: Blue | Green | Red
    [Clear Filters button]
  Products Grid

The Products Filters block receives available filter options from the parent Products block via context. Available filters update dynamically based on:

• Selected category (if any)
• Current search query (if any)
• Products currently being displayed

This ensures customers only see filters that are relevant to their current view.

Technical Details

CSS Classes

The block uses standard block wrapper attributes and dropzone ID when specified.

Data Source

The Products Filters block receives data from the parent Products block via context:

• commerce-connect/productsDropzones - Available dropzone positions
• commerce-connect/productsFullPayload - Complete products data including filter options
• commerce-connect/productsIsFetching - Loading state indicator

Available filters are calculated by the Products block based on:

• Product categories synced from BigCommerce
• Product variations (attributes like size, color, material)
• Current product set (category or search results)

Filter options include:

• Product Category - BigCommerce categories
• Product Variations - Attributes configured in BigCommerce (size, color, material, etc.)

When a customer selects filters:

1. Filter selections are added to URL parameters
2. Products block re-queries with filter criteria
3. Available filters update to reflect the filtered product set
4. Products grid refreshes with filtered results

Troubleshooting

Filters not displaying

• Verify the block is inside a Products parent block
• Check that products have categories or variations in BigCommerce
• Ensure product data is synced from BigCommerce
• Review browser console for JavaScript errors

Category filters missing

• Verify products are assigned to categories in BigCommerce
• Check that category data is synced to WordPress®
• Review available filters calculation in Products block
• Ensure at least some products in the current view have categories

Variation filters missing

• Verify products have variants configured in BigCommerce
• Check that variant data (size, color, etc.) is synced to WordPress®
• Review product variation configuration in BigCommerce admin
• Ensure products in the current view have variations

Filters not updating when selections change

• Check that filter selections are being added to URL parameters
• Verify Products block is re-querying based on URL parameters
• Review browser console for API errors
• Ensure filter state is being managed correctly

Wrong filters showing for category

The Products block calculates available filters based on:

• Current category (if ?product_category= parameter exists)
• Current search query (if ?search= parameter exists)
• Product set being displayed

If wrong filters appear:

• Verify category parameter is correct in URL
• Check that products in the category have the expected variations
• Review filter calculation logic in Products block render.php

Clear filters not working

• Verify clear filters functionality removes URL parameters
• Check that Products block refreshes when parameters are cleared
• Ensure page URL updates correctly when filters are cleared

Filter selections not persisting

• Verify URL parameters are being set correctly
• Check browser history for parameter changes
• Ensure filter state is managed via URL (not just component state)
• Review pagination and sorting to ensure filter parameters persist