Commmerce Docs
← Web Components

Web Components · Product

<mmm-product-filter>

Faceted filter UI for collection / category / search pages. Reads filter definitions from window.PRODUCT_RESPONSE_*.filters and updates the URL (triggering an SSR refresh) when the shopper toggles a facet.

Overview

Filters are URL-driven: each facet checkbox toggles a query string parameter. SSR re-rendering then produces a fresh window.PRODUCT_RESPONSE_* with the new product set, the URL stays the canonical source of truth (good for sharing & SEO), and a global commmerce:filter-change event fires so analytics / sticky-add-to-cart can react.

The filter panel collapses to a drawer on mobile and supports four breakpoint- specific widths and paddings.

When to use

  • Category landing pages with structured facets.
  • Search-result pages where the result set needs filtering.
  • Pair with a sibling <mmm-loop> + <mmm-product-card> grid.

Quick start

<script src="https://v2-api-production.commmerce.com/api/v1/web-component/commmerce-sdk.js?store=sample-store"></script>

<mmm-data-source api="category.getCategory" response-key="cat" data-type="category" payload-include-filters="true">
  <mmm-product-filter data="{{window.PRODUCT_RESPONSE_CAT.filters}}"></mmm-product-filter>
  <mmm-loop data="{{window.PRODUCT_RESPONSE_CAT.products}}">
    <mmm-product-card data-product="{{item}}"></mmm-product-card>
  </mmm-loop>
</mmm-data-source>

Attributes

AttributeTypeDefaultDescription
dataJSON / template—Filter definitions. Usually wired to data="{{window.PRODUCT_RESPONSE_KEY.filters}}".
filterJSON—Legacy alias for data — pre-2.0 schema.
xl-filter-widthstring25remPanel width for viewports > 1280px.
desktop-filter-widthstring23.125remPanel width for 768px–1280px.
tablet-filter-widthstring13.75remPanel width for 430px–768px.
xl-filter-paddingstring2remPanel padding for viewports > 1280px.
desktop-filter-paddingstring1.5remPanel padding for 768px–1280px.
tablet-filter-paddingstring1remPanel padding for 430px–768px.
mobile-filter-paddingstring1remPanel padding below 430px (drawer mode).
filter-backgroundstringtransparentPanel background colour.
checkbox-default-colorstringtheme input strokeUnchecked-checkbox border colour.
checkbox-active-colorstringtheme primary textChecked-checkbox fill colour.
accent-colorstringtheme accentAccent — used for active labels, slider thumbs, etc.

Events

EventTargetPayload
commmerce:filter-changewindow{ filters: Record<string, string[]>, url: string }

Fires after the URL is updated; useful for analytics.

Live preview

store sample-store tag <mmm-product-filter>

Renders an empty panel — filter definitions are normally bound via data="{{window.PRODUCT_RESPONSE_*.filters}}" in an SSR context.

Examples

1. Standard category-page wiring

<mmm-data-source api="category.getCategory" response-key="cat" payload-include-filters="true">
  <mmm-product-filter data="{{window.PRODUCT_RESPONSE_CAT.filters}}"></mmm-product-filter>
</mmm-data-source>

2. Compact narrow filter for dense grids

<mmm-product-filter
  data="{{window.PRODUCT_RESPONSE_CAT.filters}}"
  xl-filter-width="18rem"
  desktop-filter-width="16rem"
  tablet-filter-width="12rem"
  xl-filter-padding="1.25rem"
  desktop-filter-padding="1rem">
</mmm-product-filter>

3. Dark-mode styling

<mmm-product-filter
  data="{{window.PRODUCT_RESPONSE_CAT.filters}}"
  filter-background="#0e1011"
  checkbox-default-color="#2a2e33"
  checkbox-active-color="#c8a8ff"
  accent-color="#c8a8ff">
</mmm-product-filter>

4. Listen for filter changes

window.addEventListener('commmerce:filter-change', (e) => {
  console.log('Active filters:', e.detail.filters);
  analytics.track('filter_change', { filters: e.detail.filters });
});