Commmerce Docs
← Web Components

Web Components · Header

<mmm-header-search>

Inline product-search input with debounced type-ahead, a result dropdown, a mobile modal, and an optional slide-down panel mode. Hits the storefront's product search SDK and emits result events for analytics.

Overview

On desktop the component is an input + icon. Below mobile-breakpoint (default 625px) it collapses to an icon-only trigger that opens a full-screen mobile modal — a panel slides down from the top of the page with the input and results inside.

Set slide-down="true" for a third mode: the input appears as an icon-only trigger that expands a slide-down panel beneath the header bar (good for clean, minimalist designs).

When to use

  • Inside <mmm-header> on every storefront page.
  • Standalone on a dedicated search-results page (with label-only mode).
  • Anywhere you need product type-ahead with no extra wiring.

Quick start

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

<mmm-header-search
  search-bar-width="550"
  search-bar-height="40"
  placeholder="Search products">
</mmm-header-search>

Attributes

36 inline attributes. Theme settings fill in unset values where possible.

AttributeTypeDefaultDescription
desktop-search-iconstringsample-store /search-black.svgIcon URL shown on desktop.
mobile-search-iconstringdesktop-search-iconIcon URL shown on mobile trigger.
search-bar-widthnumber550Width of the desktop input (px).
search-bar-heightnumber40Height of the desktop input (px).
search-bar-border-radiusstringtheme / 0.25remBorder-radius for the input.
search-bar-borderstring1px solid theme-strokeFull border shorthand for the input.
placeholderstringSearchPlaceholder text inside the input.
icon-heightnumber17Icon size (px) — applied to width & height.
mobile-breakpointnumber625Viewport width (px) below which the modal-trigger mode activates.
show-iconbooleantrueToggle icon visibility — useful for text-label-only triggers.
labelstring—Text rendered next to the icon. When set, the component switches to label+icon-only mode (no input on the bar).
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.
mobile-modal-topnumber33Top offset (px) of the mobile modal panel.
mobile-modal-backgroundstringrgba(0,0,0,0)Modal backdrop colour.
mobile-modal-z-indexnumber9999Stacking context for the mobile modal.
mobile-modal-padding-topnumber20Top padding inside the mobile modal (px).
mobile-modal-max-widthnumber700Max width of the mobile modal panel (px).
mobile-modal-border-colorstring#cccBorder colour of the modal panel.
mobile-modal-border-widthnumber1Border width (px).
mobile-modal-border-radiusnumber0Border-radius of the modal panel (px).
mobile-search-icon-position-leftstringautoCSS left for the close icon inside the mobile panel.
mobile-search-icon-position-topnumber12CSS top (px) for the close icon.
mobile-search-icon-position-rightnumber10CSS right (px) for the close icon.
focus-border-colorstringtheme / #000Input border colour when focused.
dropdown-border-colorstringtheme / #d1d5dbBorder colour for the results dropdown.
dropdown-item-colorstringtheme / #111Item text colour (price / secondary).
dropdown-item-name-colorstringtheme / #111Item product-name colour.
dropdown-loading-colorstringtheme / #666Colour of the loading text inside the dropdown.
mobile-close-colorstringtheme / #666Colour of the close button inside the mobile modal.
slide-downbooleanfalseSwitch to slide-down mode — icon-only trigger expands a horizontal panel under the header.
slide-down-bgstring#ffffffBackground of the slide-down panel.
slide-down-border-colorstring#e5e5e5Border colour of the slide-down panel.
slide-down-actionstring/searchURL the form submits to in slide-down mode.
slide-down-input-namestringqName attribute for the submitted input.
slide-down-z-indexnumber999999Stacking context for the slide-down panel.
slide-down-max-widthnumber600Max width of the slide-down input (px).

Events

EventTargetPayload
search-completeelement{ query: string, results: Product[] }
mobile-search-openelement{}
mobile-search-closeelement{}
search-result-clickelement{ product: Product }

Live preview

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

Examples

<mmm-header-search
  search-bar-width="500"
  search-bar-height="40"
  placeholder="Search the store">
</mmm-header-search>

2. Icon + label trigger (compact header)

<mmm-header-search
  label="Search"
  label-color="#fff"
  label-font-size="0.75rem"
  label-letter-spacing="0.2em">
</mmm-header-search>

3. Slide-down search panel

<mmm-header-search
  slide-down="true"
  slide-down-bg="#ffffff"
  slide-down-border-color="#e5e5e5"
  slide-down-max-width="600"
  slide-down-action="/search"
  slide-down-input-name="q">
</mmm-header-search>

4. Listen for result clicks

const search = document.querySelector('mmm-header-search');
search.addEventListener('search-result-click', (e) => {
  analytics.track('search_click', {
    productId: e.detail.product.id,
    productName: e.detail.product.name
  });
});