Correct and idiomatic ways to use the <mds-header> component, ordered from most common to most specialized. Patterns assume a working knowledge of the shared component rules in agents/conventions.md.

Minimal Header with Navigation Bar

The default form. Place exactly one <mds-header-bar> in the default slot. The bar receives the menu and nav breakpoint settings from the parent automatically; without a menu slot set menu="none", or the bar shows a hamburger that opens nothing.

<mds-header menu="none">
  <mds-header-bar>
    <mds-img class="w-800" src="/logo.svg" alt="Logo"></mds-img>
    <mds-button slot="nav" label="Accedi" variant="dark" tone="outline"></mds-button>
    <mds-button slot="nav" label="Registrati" variant="primary" tone="strong"></mds-button>
  </mds-header-bar>
</mds-header>

Mobile Menu via the menu Slot

Provide a [slot="menu"] child to enable the hamburger-triggered side modal. When this slot is filled, the mobile menu icon is shown according to the menu breakpoint prop; without it the hamburger still shows and opens nothing, so set menu="none".

<mds-header menu="mobile">
  <mds-header-bar>
    <mds-img class="w-800" src="/logo.svg" alt="Logo"></mds-img>
    <mds-button slot="nav" label="Accedi" variant="dark" tone="outline"></mds-button>
  </mds-header-bar>

  <div slot="menu">
    <div class="p-600">
      <mds-button label="Accedi" variant="dark" tone="outline"></mds-button>
      <mds-button label="Registrati" variant="primary" tone="strong"></mds-button>
    </div>
  </div>
</mds-header>

Inline Appearance (Floating Bar)

Set appearance="inline" to detach the bar from the top edge and give it a rounded, floating look. A blurred backdrop is shown by default; add hide-backdrop to remove it.

<mds-header appearance="inline">
  <mds-header-bar>
    <mds-img class="w-800" src="/logo.svg" alt="Logo"></mds-img>
    <mds-button slot="nav" label="Accedi" variant="dark" tone="outline"></mds-button>
  </mds-header-bar>
</mds-header>

Scroll-Driven Appearance Change via appearance-set

Use appearance-set to declare an initial appearance, a changed appearance, and a scroll threshold in pixels. The component swaps appearance automatically as the page scrolls past the threshold - no JavaScript needed. Do not combine appearance-set with manual writes to appearance.

<!-- Starts inline (floating), switches to stripe (full-width) after 300 px of scroll -->
<mds-header appearance-set="inline, stripe 300" appearance="inline">
  <mds-header-bar>
    <mds-img class="w-800" src="/logo.svg" alt="Logo"></mds-img>
  </mds-header-bar>
</mds-header>

Auto-Hide on Downward Scroll

Set auto-hide to the pixel offset at which the bar should start hiding when the user scrolls down. The bar reappears when the user scrolls back up. Use threshold (default 1) to control how many pixels of reverse-scroll are required before the bar snaps back - raise it to reduce twitchiness.

<mds-header auto-hide="300" threshold="10">
  <mds-header-bar>
    <mds-img class="w-800" src="/logo.svg" alt="Logo"></mds-img>
    <mds-button slot="nav" label="Accedi" variant="dark" tone="outline"></mds-button>
  </mds-header-bar>
</mds-header>

Controlling Menu and Nav Breakpoints

menu controls on which viewports the hamburger icon is visible; nav controls on which viewports the inline navigation is visible. Both accept 'all', 'desktop', 'mobile', or 'none'.

<!-- Hamburger shown on all screen sizes; inline nav shown only on desktop -->
<mds-header menu="all" nav="desktop">
  <mds-header-bar>
    <mds-img class="w-800" src="/logo.svg" alt="Logo"></mds-img>
    <mds-button slot="nav" label="Accedi" variant="dark" tone="outline"></mds-button>
  </mds-header-bar>

  <div slot="menu">
    <div class="p-600">
      <mds-button label="Accedi" variant="dark" tone="outline"></mds-button>
    </div>
  </div>
</mds-header>

Reacting to Visibility Changes

Listen for mdsHeaderVisibilityChange to know when the bar is hidden or shown by auto-hide. The event detail carries visibility as the string 'visible' or 'hidden'.

<mds-header auto-hide="200" id="siteHeader">
  <mds-header-bar>
    <mds-img class="w-800" src="/logo.svg" alt="Logo"></mds-img>
  </mds-header-bar>
</mds-header>

<script>
  document.getElementById('siteHeader').addEventListener('mdsHeaderVisibilityChange', (e) => {
    console.log('header visibile:', e.detail.visibility);
  });
</script>

Reacting to Mobile Menu Close

Listen for mdsHeaderClose to run cleanup logic when the side modal is dismissed. The event detail carries the bound <mds-header-bar> reference.

<mds-header id="siteHeader">
  <mds-header-bar>
    <mds-img class="w-800" src="/logo.svg" alt="Logo"></mds-img>
  </mds-header-bar>
  <div slot="menu">
    <mds-button label="Accedi" variant="dark" tone="outline"></mds-button>
  </div>
</mds-header>

<script>
  document.getElementById('siteHeader').addEventListener('mdsHeaderClose', (e) => {
    console.log('menu chiuso, bar:', e.detail.bar);
  });
</script>

Programmatic Open/Close via setOpened()

Use the setOpened() method to open or close the mobile menu from JavaScript - for example after a navigation event inside the menu panel.

<mds-header id="siteHeader">
  <mds-header-bar>
    <mds-img class="w-800" src="/logo.svg" alt="Logo"></mds-img>
  </mds-header-bar>
  <div slot="menu">
    <mds-button label="Vai alla home" id="homeBtn" variant="primary" tone="strong"></mds-button>
  </div>
</mds-header>

<script>
  document.getElementById('homeBtn').addEventListener('click', async () => {
    window.location.href = '/';
    await document.getElementById('siteHeader').setOpened(false);
  });
</script>

Styling Customization

Customize the header through its documented --mds-header-* CSS custom properties. Use the semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast continue to work.

mds-header {
  --mds-header-color: rgb(var(--magma-text-muted));
  --mds-header-icon-color: rgb(var(--magma-accent-fg));
  --mds-header-z-index: 200;
}

/* Inline appearance: wider floating margin on desktop */
mds-header[appearance='inline'] {
  --mds-header-inline-margin: 2rem;
  --mds-header-backdrop-blur-strength: 4px;
}