Commmerce Docs
← Web Components

Web Components · Header

<mmm-header>

The top-level header container — a sticky / fixed / static shell with hero-image, banner-from-slider, hide-on-scroll, and scrolled-state theming. Slots its children (<mmm-header-logo>, search, cart, navigation) into the page.

Overview

<mmm-header> wraps the rest of the header components. Its shadow DOM provides only positioning, background, and scroll behaviour — every visible element (logo, nav, search, cart, account, wishlist) is a child in the light DOM that slots through. The component is theme-aware via CommmerceThemeSettings but every visual attribute can be overridden inline.

Three behaviours worth knowing:

  • Banner-from-slider — if the page contains an <mmm-slider>, the header auto-captures its first image to localStorage and uses it as a hero background on the home page until the user scrolls past the slider.
  • Hide-on-scroll — translates the header off-screen on scroll-down and back on scroll-up once scroll-threshold is exceeded.
  • Scrolled state — adds a .header-scrolled class once the page is past the threshold, letting you change background and shadow.

When to use

  • Every storefront page — the canonical site header.
  • When you need a sticky top bar that pins above content.
  • Home pages with a hero banner you want the header to fade into.
  • Mobile-friendly headers that hide on scroll-down and reveal on scroll-up.

Quick start

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

<mmm-header position="sticky" background-color="#ffffff" hide-on-scroll="true">
  <mmm-header-logo></mmm-header-logo>
  <mmm-header-navigation-desktop navigation-id="main"></mmm-header-navigation-desktop>
  <mmm-header-search></mmm-header-search>
  <mmm-header-cart></mmm-header-cart>
</mmm-header>

Attributes

AttributeTypeDefaultDescription
positionstringstickystatic, relative, sticky, fixed, absolute.
topstring0CSS top offset. Plain numbers get px appended automatically.
leftstring0Applied only when position="fixed".
rightstring0Applied only when position="fixed".
z-indexnumber1000Stacking context. Raise above any overlays.
widthstring100%Width of the shell.
max-widthstring100%Cap for the header width.
background-colorstringtransparentSolid background. Ignored when a hero image is showing.
background-imagestringnoneCSS background-image value — usually url('...').
background-sizestringcoverCSS background-size.
background-positionstringcenterCSS background-position.
background-repeatstringno-repeatCSS background-repeat.
box-shadowstringnoneStatic box-shadow (when not scrolled).
border-bottomstringnoneStatic border-bottom.
transitionstringall 0.3s easeCSS transition applied to :host.
hide-on-scrollbooleanfalseTranslate the header off-screen on scroll-down past scroll-threshold; reveal on scroll-up.
scroll-thresholdnumber100Scroll distance (px) before scroll-behaviour activates.
scroll-shadowstring—Box-shadow to apply once .header-scrolled is active.
scroll-background-colorstring—Background-color to apply once .header-scrolled is active. Ignored if a hero image is showing.
hero-imagestring—Explicit hero image URL. Wins over banner-from-slider. Shown only on non-home pages by default.
banner-imagebooleantrueWhen false, disables the banner-from-slider hero entirely. Keep enabled for stores that use a home-page slider.
home-slugstring/Comma-separated list of paths the header treats as "home" (for picking when the hero image shows). Example: /, /en, /us.

Events

The header does not emit custom events itself — it listens to scroll, popstate, and history pushState/replaceState to keep its hero image and scrolled class in sync with the route.

Live preview

store sample-store tag <mmm-header>

Renders against sample-store.commmerce.com with one logo and one cart icon nested inside.

Examples

1. Sticky header that hides on scroll

<mmm-header
  position="sticky"
  background-color="#ffffff"
  hide-on-scroll="true"
  scroll-threshold="120"
  scroll-shadow="0 0.125rem 0.5rem rgba(0,0,0,0.08)"
  scroll-background-color="rgba(255,255,255,0.95)">
  <mmm-header-logo></mmm-header-logo>
  <mmm-header-cart></mmm-header-cart>
</mmm-header>

2. Header with explicit hero image on non-home pages

<mmm-header
  position="sticky"
  hero-image="https://cdn.commmerce.com/sample-store/banners/category-hero.jpg"
  home-slug="/">
  <mmm-header-logo></mmm-header-logo>
  <mmm-header-navigation-desktop navigation-id="main"></mmm-header-navigation-desktop>
</mmm-header>

3. Static header with no scroll behaviour

<mmm-header
  position="static"
  banner-image="false"
  background-color="#000"
  border-bottom="1px solid #1f1f1f">
  <mmm-header-logo></mmm-header-logo>
  <mmm-header-search></mmm-header-search>
  <mmm-header-cart></mmm-header-cart>
</mmm-header>