@data-slot/navigation-menu

Headless navigation menu (mega menu) component for vanilla JavaScript. Accessible, unstyled, tiny.

Installation

npm install @data-slot/navigation-menu

Quick Start

<nav data-slot="navigation-menu">
  <ul data-slot="navigation-menu-list">
    <li data-slot="navigation-menu-item" data-value="products">
      <button data-slot="navigation-menu-trigger">Products</button>
      <div data-slot="navigation-menu-content">
        <a href="/product-a">Product A</a>
        <a href="/product-b">Product B</a>
      </div>
    </li>
    <li data-slot="navigation-menu-item" data-value="company">
      <button data-slot="navigation-menu-trigger">Company</button>
      <div data-slot="navigation-menu-content">
        <a href="/about">About</a>
        <a href="/careers">Careers</a>
      </div>
    </li>
    <li data-slot="navigation-menu-indicator" role="presentation" aria-hidden="true"></li>
  </ul>
  <div data-slot="navigation-menu-portal">
    <div data-slot="navigation-menu-positioner">
      <div data-slot="navigation-menu-popup">
        <div data-slot="navigation-menu-viewport"></div>
      </div>
    </div>
  </div>
</nav>

<script type="module">
  import { create } from "@data-slot/navigation-menu";
  
  const controllers = create();
</script>

Minimal markup that only authors navigation-menu-viewport still works. The runtime generates the popup stack while the menu is open and restores the original DOM on close.

API

Initialization

create(scope?)

Auto-discover and bind all navigation menu instances in a scope (defaults to document).

import { create } from "@data-slot/navigation-menu";

const controllers = create(); // Returns NavigationMenuController[]

createNavigationMenu(root, options?)

Create a controller for a specific element.

import { createNavigationMenu } from "@data-slot/navigation-menu";

const menu = createNavigationMenu(element, {
  delayOpen: 0,
  delayClose: 0,
  onValueChange: (value) => console.log(value),
});

Slots

Runtime Slots

• navigation-menu - Root navigation element that manages the active panel and open state.
• navigation-menu-list - Required top-level list containing navigation items; used to discover top-level hover and focus targets.
• navigation-menu-item - Container for a navigation entry; at least one item is required. Use data-value to identify an entry with a content panel.
• navigation-menu-trigger - Button inside an item that opens its associated content panel.
• navigation-menu-content - Content panel inside an item, displayed when that item is active.
• navigation-menu-indicator - Optional animated highlight that follows top-level hover/focus targets and stays anchored to the active trigger while a panel is open.
• navigation-menu-portal - Portal wrapper moved to document.body while the menu is open.
• navigation-menu-positioner - Popup positioning wrapper that receives resolved side/alignment attributes and sizing variables.
• navigation-menu-popup - Animated popup shell around the viewport.
• navigation-menu-viewport - Optional clipping viewport that holds the active content panel.
• navigation-menu-viewport-positioner - Deprecated alias for navigation-menu-positioner.

Generated Slots

• navigation-menu-bridge - Runtime-created hover safety shield that keeps the menu open while crossing the gap to its content.
• navigation-menu-safe-triangle - Runtime-created debug polygon that visualizes the hover safety corridor when debugging is enabled.

Markup

<nav data-slot="navigation-menu">
  <ul data-slot="navigation-menu-list">
    <li data-slot="navigation-menu-item" data-value="unique-id">
      <button data-slot="navigation-menu-trigger">Label</button>
      <div data-slot="navigation-menu-content">
        <!-- Links, content -->
      </div>
    </li>
    <!-- Optional hover indicator -->
    <li data-slot="navigation-menu-indicator" role="presentation" aria-hidden="true"></li>
  </ul>
  <div data-slot="navigation-menu-portal">
    <div data-slot="navigation-menu-positioner">
      <div data-slot="navigation-menu-popup">
        <div data-slot="navigation-menu-viewport"></div>
      </div>
    </div>
  </div>
</nav>

If you only author navigation-menu-viewport, the runtime synthesizes the missing navigation-menu-portal, navigation-menu-positioner, and navigation-menu-popup wrappers while the menu is open.

Data Attributes

Options can also be set via data attributes on the root element. JS options take precedence.

Boolean attributes: present or "true" = true, "false" = false, absent = default.

Placement attributes (data-side, data-align, data-side-offset, data-align-offset) control how the viewport is positioned relative to the active trigger:

• start - Align viewport left edge with trigger left edge (default)
• center - Center viewport under trigger
• end - Align viewport right edge with trigger right edge

Can be set on:

1. navigation-menu-content (highest priority, per-panel)
2. navigation-menu-item
3. navigation-menu root (lowest priority, global default)

navigation-menu-positioner is the canonical popup positioning slot. Its data-side / data-align are mirrored output values and are not used as placement inputs. navigation-menu-viewport-positioner is still accepted as a legacy alias.

<!-- Faster hover response with focus auto-open opt-in -->
<nav data-slot="navigation-menu" data-delay-open="100" data-open-on-focus="true">
  ...
</nav>

<!-- Center-align a narrow submenu under its trigger -->
<li data-slot="navigation-menu-item" data-value="company" data-align="center">
  <button data-slot="navigation-menu-trigger">Company</button>
  <div data-slot="navigation-menu-content">
    <a href="/about">About</a>
    <a href="/careers">Careers</a>
  </div>
</li>

Output Attributes

data-activation-direction is only emitted while switching between open top-level panels. A full close is intentionally non-directional.

Options

Content mounting and server rendering

By default, Navigation Menu removes its closed panels from the page’s DOM. This keeps pages with large menus smaller after initialization. The menu buttons and links outside those panels stay in the page.

Opening a panel puts the same content back into the page. Its state and event listeners are preserved. When switching panels, the new panel appears while the previous one finishes its exit animation. After that animation, the previous panel is removed.

Closing the menu waits for the panels and their surrounding popup to finish their exit animations. Reopening a panel during its exit animation keeps it in the page.

Most applications can use this default without any changes.

If your code needs to find or update links inside a closed panel—for example, using querySelector—use eager mode to keep the panels in the DOM:

createNavigationMenu(root, { mountStrategy: "eager" });

You can also add data-mount-strategy="eager" to the Navigation Menu root. A JavaScript option takes precedence over the HTML attribute.

With the default lazy mode, DOM queries won’t find closed panels or their links. You can also keep a reference to a panel before initializing Navigation Menu and use that reference later.

Server rendering and pages without JavaScript

Lazy mounting does not reduce the HTML sent to the browser. Panel content is still included in your HTML; Navigation Menu removes closed panels from the DOM after JavaScript initializes.

Make sure essential navigation works before JavaScript loads or if it never runs. You can leave the links visible until initialization, or provide separate fallback navigation if your panels start hidden. Neither lazy nor eager mode provides that fallback automatically.

Controller

Controller Destruction

destroy() permanently disposes the controller and hides any open surface without emitting an additional change event. Repeated destruction is safe; methods on the old controller become no-ops. Create a new controller on the same root to rebind it.

Events

Outbound Events

Listen for changes via custom events:

element.addEventListener("navigation-menu:change", (e) => {
  console.log("Active item:", e.detail.value);
});

Inbound Events

Control the navigation menu via events:

// Open a specific item
element.dispatchEvent(
  new CustomEvent("navigation-menu:set", { detail: { value: "products" } })
);

// Close the menu
element.dispatchEvent(
  new CustomEvent("navigation-menu:set", { detail: { value: null } })
);

Styling

navigation-menu-portal is moved to document.body while open. If authored popup-stack slots are present, they are reused. Otherwise, missing portal / positioner / popup wrappers are generated while open and removed on close.

Runtime geometry is owned by navigation-menu-positioner: position, top, left, width, and height are written inline and reset on close. navigation-menu-popup is the canonical animated shell. The active navigation-menu-content panel is mounted inside navigation-menu-viewport while open. Inactive panels are detached after their exit animation by default; eager panels return to their original markup location.

Use positionMethod: "fixed" or data-position-method="fixed" when the menu needs viewport-based anchoring, such as inside sticky headers.

Basic Styling

/* Hidden by default */
[data-slot="navigation-menu-content"] {
  display: none;
}

[data-slot="navigation-menu-content"][data-open] {
  display: block;
}

/* Positioner owns placement geometry */
[data-slot="navigation-menu-positioner"],
[data-slot="navigation-menu-viewport-positioner"] {
  top: 0;
  left: 0;
  transition: top 0.3s, left 0.3s;
}

/* Skip initial position animation */
[data-slot="navigation-menu-positioner"][data-instant],
[data-slot="navigation-menu-viewport-positioner"][data-instant] {
  transition: none;
}

/* Popup owns the main shell animation */
[data-slot="navigation-menu-popup"] {
  transform-origin: var(--transform-origin);
  width: var(--popup-width);
  height: var(--popup-height);
  transition: transform 0.3s, width 0.3s, height 0.3s, opacity 0.15s;
}

[data-slot="navigation-menu-popup"][data-starting-style],
[data-slot="navigation-menu-popup"][data-ending-style] {
  opacity: 0;
}

/* Viewport keeps backward-compatible sizing aliases */
[data-slot="navigation-menu-viewport"] {
  width: var(--viewport-width);
  height: var(--viewport-height);
}

/* Skip animation on initial open */
[data-slot="navigation-menu-viewport"][data-instant] {
  transition: none;
}

/* Indicator positioning */
[data-slot="navigation-menu-indicator"] {
  position: absolute;
  left: var(--indicator-left);
  width: var(--indicator-width);
  transition: left 0.2s, width 0.2s;
}

data-instant is used for the initial open phase and for sync-driven anchor tracking updates (for example when a sticky trigger moves while the menu is open). It is cleared when switching, closing, or after the tracking update settles. Use it to skip those reposition transitions without suppressing exit animations.

Motion Animations

Use data-starting-style / data-ending-style on navigation-menu-popup for full popup open/close animations, and on navigation-menu-content for panel presence. Directional panel switching should key off data-activation-direction="left|right" on content. The active panel stays in normal flow; mounted inactive/exiting panels are absolutely positioned by the runtime so they do not affect popup measurement while they animate out.

For exit animations, avoid CSS that force-hides content immediately by data-state (for example display: none on non-active panels), because that bypasses the presence lifecycle.

[data-slot="navigation-menu-popup"][data-starting-style],
[data-slot="navigation-menu-popup"][data-ending-style] {
  opacity: 0;
  transform: scale(0.96);
}

[data-slot="navigation-menu-content"][data-starting-style],
[data-slot="navigation-menu-content"][data-ending-style] {
  opacity: 0;
}

[data-slot="navigation-menu-content"][data-starting-style][data-activation-direction="right"] {
  transform: translateX(2rem);
}

[data-slot="navigation-menu-content"][data-starting-style][data-activation-direction="left"] {
  transform: translateX(-2rem);
}

[data-slot="navigation-menu-content"][data-ending-style][data-activation-direction="right"] {
  transform: translateX(-2rem);
}

[data-slot="navigation-menu-content"][data-ending-style][data-activation-direction="left"] {
  transform: translateX(2rem);
}

Legacy data-motion and --motion-direction are still emitted during panel switches for backward compatibility. That includes both root-level and content-level data-motion output, but data-activation-direction is the canonical directional hook.

--popup-width / --popup-height are the popup shell size vars. While the menu is open, they stay at fixed pixel values so CSS can animate panel-to-panel size changes directly between px targets. Initial open writes the measured size synchronously; the shell does not need an auto reset while open.

CSS Variables

Deprecated Compatibility

• navigation-menu-viewport-positioner is a deprecated alias for navigation-menu-positioner.
• --viewport-width, --viewport-height, root/content data-motion, and --motion-direction are deprecated and planned for removal in the next major release.
• Content-wrapped navigation-menu-portal / navigation-menu-positioner shells are restore-only compatibility and are also planned for removal in the next major release.

Keyboard Navigation

Within Top-Level Items

Top-level submenu triggers and plain links remain in the natural tab order.

Within Content Panel

Behavior

• Hover: Opens after delayOpen ms, closes after delayClose ms
• Click: Locks menu open until explicit action (click same trigger, click another trigger, click outside, or Escape); hover does not switch/close while locked
• Focus: Does not auto-open by default; set openOnFocus / data-open-on-focus="true" to opt in
• Trigger open focus:
  • Pointer click/tap keeps focus on the trigger
  • Keyboard activation/programmatic click moves focus into menu content (first focusable item, or content panel fallback)
• Indicator: Plain top-level links participate in indicator positioning when no submenu is open; open submenu state takes precedence
• Switching: Instant transition between items (no delay)

License

MIT