Commmerce Docs
← Web Components

Web Components · Header

<mmm-header-cart>

Cart icon with a live item-count badge. Click opens the cart slider (default) or navigates to /cart. Subscribes to cart events so the badge stays in sync without polling.

Overview

Initial count is read from CommmerceUtils.getStoreConfig().cart_count (falls back to window.STORE_INFO_DATA.cart_count). The element listens for commmerce:cart-updated, commmerce:add-to-cart, and commmerce:remove-from-cart on window to live-update the badge.

Clicking dispatches cart-click on the element and (in default mode) commmerce:open-cart-slider on window — the slider component listens for that event. Set open-cart-slider="false" to navigate to the href URL instead.

When to use

  • Inside <mmm-header> on every storefront page.
  • Anywhere you need a cart icon with live count.
  • For minimal headers — pair with label for an icon+text style.

Quick start

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

<mmm-header-cart></mmm-header-cart>

Attributes

AttributeTypeDefaultDescription
iconstringsample-store / cart-black.svgIcon image URL.
icon-widthstring1.0625remIcon width — CSS length.
icon-heightstring1.0625remIcon height — CSS length.
icon-filterstringnoneCSS filter applied to the icon image (e.g. brightness(0) invert(1) turns a black SVG white). The count badge is not affected.
button-sizestring2.375remWidth & height of the round button.
border-colorstringtheme / #e5e7ebBorder colour around the icon button.
background-colorstring#fffBackground colour of the icon button.
hover-background-colorstringtheme / #333Background colour on hover.
hover-border-colorstringtheme / #e5e7ebBorder colour on hover.
count-badge-colorstringtheme add-to-cart fill / #000Background of the count badge.
count-text-colorstringtheme add-to-cart text / #fffText colour inside the count badge.
count-sizestring1.125remWidth & height of the count badge (desktop).
count-badge-topstring-0.5remCSS top offset of the count badge.
count-badge-rightstring-0.5remCSS right offset of the count badge.
mobile-count-sizestring0.875remWidth & height of the count badge on mobile.
mobile-count-badge-topstring-0.375remMobile top offset for the count badge.
mobile-count-badge-rightstring-0.375remMobile right offset for the count badge.
mobile-hover-background-colorstringnoneHover background on mobile.
mobile-hover-borderstring1px solid #b6b3b3Hover border on mobile.
mobile-show-circular-backgroundbooleantrueWhether the circular button background is shown on mobile.
hrefstring/cartURL used when open-cart-slider="false".
targetstring_selfAnchor target for navigation mode.
open-cart-sliderbooleantrueWhen true, click opens <commmerce-cart-slider> instead of navigating.
show-circular-backgroundbooleantrueToggle the circular button border + background. Set false for an icon-only style.
show-iconbooleantrueWhether the icon image renders at all.
labelstring—Optional text next to the icon. Switches the button to label+icon layout.
label-colorstring#111111Colour of the label text.
label-font-sizestring0.75remFont size of the label.
label-font-weightstring600Font weight of the label.
label-letter-spacingstring0.18emLetter-spacing of the label.

Events

EventTargetPayload
cart-clickelement{ count: number }
commmerce:open-cart-sliderwindow{}

Listens on window: commmerce:cart-updated, commmerce:add-to-cart, commmerce:remove-from-cart to refresh the badge count.

Live preview

store sample-store tag <mmm-header-cart>

Examples

1. Default — opens cart slider on click

<mmm-header-cart></mmm-header-cart>

2. Navigate to /cart instead of opening the slider

<mmm-header-cart
  open-cart-slider="false"
  href="/cart"
  target="_self"></mmm-header-cart>

3. Icon + label in dark header

<mmm-header-cart
  label="Bag"
  label-color="#fff"
  show-circular-background="false"
  icon-filter="brightness(0) invert(1)"
  count-badge-color="#ff3366"></mmm-header-cart>

4. Listen for clicks to fire analytics

const cart = document.querySelector('mmm-header-cart');
cart.addEventListener('cart-click', (e) => {
  analytics.track('cart_open', { itemCount: e.detail.count });
});