mobile-menu

Responsive mobile navigation menu with hamburger toggle and popover panel.

Overview

The <mobile-menu> element provides responsive navigation that activates at a configurable viewport breakpoint. Below the breakpoint, it shows a hamburger toggle and hides sibling <nav> and <site-tools> elements in the parent header. Above the breakpoint, it hides itself completely.

The menu panel uses the native HTML popover API for the overlay, with backdrop support and keyboard accessibility built in.

Attributes

Attribute	Type	Default	Description
`breakpoint`	CSS length	`52rem`	Viewport width below which mobile mode activates

Basic Usage

Place <mobile-menu> inside a <header> alongside the desktop navigation. The trigger button must have data-trigger and popovertarget pointing to the panel.

<nav class="horizontal pills" aria-label="Main navigation">
    <ul>
      <li><a href="/about">About</a></li>
      <li><a class="active-parent" href="/docs">Docs</a></li>
      <li><a href="/blog">Blog</a></li>
    </ul>
  </nav>

<site-tools>
    <site-search>
      <button type="button" data-trigger="" class="ghost">Search</button>
    </site-search>
  </site-tools>

<mobile-menu breakpoint="52rem">
    <button type="button" data-trigger="" popovertarget="main-menu" aria-label="Menu">
      <icon-wc name="menu"></icon-wc>
    </button>
  </mobile-menu>
</header>

<nav popover="" id="main-menu" class="mobile-menu-panel">
  <button type="button" class="mobile-menu-close" popovertarget="main-menu" popovertargetaction="hide" aria-label="Close">
    <icon-wc name="x"></icon-wc>
  </button>
  <ul>
    <li><a href="/about">About</a></li>
    <li><a class="active-parent" href="/docs">Docs</a></li>
    <li><a href="/blog">Blog</a></li>
  </ul>
</nav>

CSS Tokens

Theme the panel appearance with these custom properties:

Token	Default	Description
`--mobile-menu-bg`	`var(--color-surface)`	Panel background
`--mobile-menu-radius`	`var(--radius-m)`	Panel border radius
`--mobile-menu-shadow`	Subtle shadow	Panel box shadow
`--mobile-menu-padding`	`var(--size-l)`	Panel padding
`--mobile-menu-max-width`	`280px`	Panel maximum width
`--mobile-menu-backdrop`	Semi-transparent black	Backdrop overlay color

How It Works

On connectedCallback, the component creates a matchMedia observer for the configured breakpoint.
When the viewport crosses the breakpoint, it sets or removes [data-mobile] on itself.
In mobile mode, the component hides sibling <nav> and <site-tools> elements in the parent header.
When switching back to desktop, it restores sibling visibility and closes any open popover.

Without JavaScript, the element stays hidden (display: none by default). This is progressive enhancement — the desktop nav remains functional.

Accessibility

The trigger button should have aria-label="Menu" for screen readers.
The popover panel uses the native popover API which provides focus trapping and Esc to close.
Include a close button inside the panel with popovertargetaction="hide".

site-tools — Site-wide utility container
brand-mark — Brand logo display
drop-down — Desktop dropdown menus
Navbar pattern — Complete navigation patterns

Welcome to Vanilla Breeze