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

Standard Header Bar with Logo and Navigation

The canonical form. Place branding content in the default slot (left side) and <mds-button> elements in the nav slot (right side). With the defaults (menu="mobile" and nav="desktop") the nav is visible on desktop and the hamburger appears only on mobile.

<mds-header-bar>
  <div class="flex gap-200 items-center">
    <mds-img src="./logo.svg"></mds-img>
    <mds-text typography="h6">Portale Enti</mds-text>
  </div>
  <mds-button slot="nav" variant="dark" tone="outline">Accedi</mds-button>
  <mds-button slot="nav" variant="primary" tone="strong">Registrati</mds-button>
</mds-header-bar>

Nested Inside mds-header

<mds-header-bar> is a structural sub-component of mds-header. Place it inside <mds-header> so that the hamburger click is wired to the drawer automatically; the component calls mds-header.setOpened(true) on its nearest mds-header ancestor.

<mds-header>
  <mds-header-bar>
    <mds-text typography="h6">Gestione Pratiche</mds-text>
    <mds-button slot="nav" variant="dark" tone="text" icon="mi/baseline/person">Account</mds-button>
    <mds-button slot="nav" variant="primary" tone="strong">Nuovo documento</mds-button>
  </mds-header-bar>
  <!-- drawer and other header regions go here -->
</mds-header>

Controlling Hamburger Visibility

Use the menu prop to decide when the hamburger button is shown (inside mds-header, set menu and nav on mds-header: it overwrites the bar’s values when it loads). The default mobile is correct for most apps. Use all when you always want a drawer-style menu regardless of viewport, or none to remove the hamburger entirely (e.g. a public marketing bar with no drawer).

<!-- Always show the hamburger (single-column layout, any viewport) -->
<mds-header-bar menu="all">
  <mds-text typography="h6">Area Personale</mds-text>
</mds-header-bar>

<!-- No hamburger at all (branding-only bar) -->
<mds-header-bar menu="none">
  <mds-img src="./logo.svg"></mds-img>
</mds-header-bar>

Controlling Inline Navigation Visibility

Use the nav prop symmetrically with menu. The default desktop shows the nav slot only on wide viewports. Set nav="all" to always show inline links, nav="mobile" to show them only on small screens, or nav="none" to suppress the nav region entirely.

<!-- Always show inline nav (no responsive collapsing) -->
<mds-header-bar menu="none" nav="all">
  <mds-img src="./logo.svg"></mds-img>
  <mds-button slot="nav" variant="dark" tone="text">Chi siamo</mds-button>
  <mds-button slot="nav" variant="dark" tone="text">Servizi</mds-button>
  <mds-button slot="nav" variant="primary" tone="strong">Contatti</mds-button>
</mds-header-bar>

Listening for the Hamburger Open Event

Listen to mdsHeaderBarOpen (bubbles) to react when the user taps the hamburger - for example to track analytics or to open a custom side panel not managed by mds-header.

<mds-header-bar id="main-bar">
  <mds-text typography="h6">Applicazione</mds-text>
</mds-header-bar>

<script>
  document.getElementById('main-bar').addEventListener('mdsHeaderBarOpen', () => {
    console.log('menu aperto');
  });
</script>

Programmatic Open via setOpened

The bar’s own setOpened(isOpened) only records the state and renders nothing. To open or close the drawer from external code - for instance after route navigation in a single-page app - call setOpened on the surrounding mds-header.

<mds-header id="main-header">
  <mds-header-bar>
    <mds-text typography="h6">Dashboard</mds-text>
  </mds-header-bar>
  <div slot="menu">
    <mds-button label="Pratiche" variant="dark" tone="text"></mds-button>
  </div>
</mds-header>

<script>
  // Close the drawer after the user selects a menu item
  const header = document.getElementById('main-header');
  header.setOpened(false);
</script>

Styling the Hamburger Icon Color

Use --mds-header-bar-hamburger-color to theme the hamburger icon. Set it on the host element or a parent selector; use a semantic color role wrapped with rgb(var(--magma-<role>)) so dark-mode works automatically.

mds-header-bar {
  --mds-header-bar-hamburger-color: rgb(var(--magma-accent-fg));
}

Styling via Shadow Parts

The four documented shadow parts (content, actions, nav, hamburger) let you adjust layout without piercing the shadow DOM. Target only these documented parts.

/* Increase the gap between the nav buttons and the hamburger */
mds-header-bar::part(actions) {
  gap: calc(var(--spacing) * 600);
}

/* Visually highlight the hamburger button in a branded theme */
mds-header-bar::part(hamburger) {
  border-radius: var(--magma-radius-md);
  background-color: rgb(var(--magma-accent-surface));
}