Product filtering toolkit

Product Filtering Toolkit

Product filtering (also known as faceted search) enables shoppers to refine product searches based on multiple attributes like price, size, ratings, etc. For a store owner's view of administering this feature, please see product filtering settings (Help Center) (opens in a new tab).



  • Adding product filtering to a theme is recommended for experienced theme developers only. You must have facility with HTML and CSS, and must also familiarize yourself with how BigCommerce themes are structured and operate.
  • Product filtering is a Pro/Enterprise feature. To enable it on an active public store, you must upgrade to a Pro or Enterprise plan.
  • As noted below, we recommend implementing product filtering on a temporary sandbox store. You can create a trial store, and then upload your theme customizations to that store via WebDAV to replicate your local changes.

Creating a New Theme with Product Filtering

Product filtering is fully functional in the Blueprint base theme. Once you’ve enabled Developer Mode, you’ll be able to access this base theme and add product filtering to your developer store.


Restricted/Grandfathered Access to Blueprint Base Theme

The Blueprint base theme is now available only to stores that applied it before November 2016.

As of that date, stores are being offered themes only from BigCommerce's new Stencil theme platform. Within a store's control panel, the Themes Marketplace and My Themes pages will show only those Blueprint themes that have been applied to the store and/or purchased before November 2016.

For information about developing on the current Stencil platform, please see this developer documentation.

Enabling Product Filtering for Your Customized Theme

To enable product filtering, just enable Developer Mode on your store. This will enable product filtering on your store by default, regardless of whether or not your theme and plan support it.


Start with a Sandbox Store

Depending on the customizations you have made to your theme, enabling Developer Mode could have unexpected results. We recommend using a sandbox store (not your main store) when applying these changes for the first time.

If you are working with a new store, product filtering might already work out-of-the-box for your theme.

Implementing Product Filtering in Your Theme

Once you’ve enabled product filtering for your sandbox store, you’ll need to get the most up-to-date Blueprint files and copy them into your own theme. Here is how to do so.


Restricted/Grandfathered Access to Blueprint Base Theme

As noted above, the Blueprint base theme is now available only to stores that applied it before November 2016.

  1. Enable Developer Mode in your sandbox store, if you haven’t already. This will enable the Blueprint theme and the faceted search feature.
  2. Unless you’re starting from scratch, back up your theme customizations.
  3. Select Blueprint as your store’s theme.
  4. Download the Blueprint theme – don’t worry, you’ll only need certain files for faceted search.
  5. Restore your theme from the backups you downloaded in step 2.
  6. Upload the following files from Blueprint to your sandbox store:
  • Panels/FacetedSearch.html – This panel contains the markup for your Faceted Search column. It calls all the panels for each of the searchable facets as well.
  • Panels/FacetedSearchProductGrid.html - This panel contains the markup for your list of product results when your category lists are set to "grid view".
  • Panels/FacetedSearchProductList.html - This panel contains the markup for your list of product results when your category lists are set to "list view".
  • Panels/FacetedSearchTemplateCategory.html – The panel that contains the markup for the Category facet.
  • Panels/FacetedSearchTemplateMultichoice.html – The panel that contains the markup for any facet containing multiple-choice check boxes.
  • Panels/FacetedSearchTemplateRange.html – The panel that contains the markup for facets containing ranges.
  • Panels/FacetedSearchTemplateRating.html – The panel that contains the markup for the Rating facet.
  • Panels/FacetedSearchTemplateShowing.html – The panel that contains the markup for the list of currently selected filters.
  • Panels/FacetedSearchTemplateSingle.html – The panel that contains the markup for any facet containing single-choice radio buttons.
  • Panels/Pagination.html – The panel that contains the markup for your pagination – note that this will not use any existing pagination panels that your theme may have.
  • Styles/faceted-search.css – This will be included in FacetedSearch.html, so you don’t need to add it to your HTMLHead.html file.
  1. Copy your brands.html page and name it brands_with_facets.html.
  2. Copy your search.html page and name it search_with_facets.html.
  3. Copy your category.html page and name it category_with_facets.html.
  4. Include the required assets on your new facets pages. You can use the facets pages from Blueprint for reference (the assets will be named the same):
  • %%Panel.FacetedSearch%% – This is the main Faceted Search panel, and will call the rest of the panels it needs accordingly (including required JavaScript and CSS).
  • Add the js-faceted-search-column class to the container of your Faceted Search panel.
  • If you have a responsive theme, you can add the Refine button to your page, which toggles the Faceted Search column on or off. By default, this button displays only on mobile:
    <button class="js-faceted-search-action btn"> %%LNG_FilterBy%% </button>
  1. If the pages mentioned above don’t exist, you can copy the existing pages from the Blueprint theme. Keep in mind that you’ll need to modify these pages to suit the structure of your theme.

Allowing For Filtering On/Off

When faceted search is switched on, the following templates will be used:

  • Brand pages > brands_with_facets.html
  • Search page > search_with_facets.html
  • Category pages > category_with_facets.html

When switched off:

  • Brand pages > brands.html
  • Search page > search.html
  • Category pages > category.html

Clone and Rename Templates, Don’t Alter Originals

Development agencies should not modify the base templates of the brand.html, search.html, or category.html pages to include faceted search. Clients who are not on a Pro or Enterprise plan do not get faceted search, so if you include it on category.html, brand.html or search.html page, your theme will be useless to those clients.

Category Filtering Details

When you turn on product filtering for a store, it will automatically switch all Category Layout Files to your new category_with_facets.html page. To view product filtering on Category pages, you must ensure that the Category Layout File is set to category_with_facets.html.

You will not see the Category filter on storefront Category pages. This has been hidden for SEO reasons.

Did you find what you were looking for?