Add a NavigationMenu component family

NavigationMenu: native site navigation with coordinated panels

Implementation specification, amended 2026-09-04. The original body (2026-08-31) transferred the confirmed Draft 9 design as amended in Draft 11. It has since been audited against the codebase, the standards and four prior-art libraries, and the maintainer settled twenty further decisions. This revision folds those in, corrects three sentences the audit proved false, and records the implementation base. All decisions below are settled. The API is not shipped and the release gates remain unpassed. Further accepted contract changes belong in this body; comments and research notes do not override it.

Problem and goals

The menubar-navigation example combines a category destination with panel disclosure. On touch, activating its Services link navigates without providing a way to open that panel. @michaelsawyers reported this in #6992. Build a dedicated family with separate native link and disclosure actions, coordinated rich panels, and the example's focus and keyboard paths. Keep existing Menu and Menubar roles and defaults unchanged.

Support plain links, button-only entries, category links with sibling disclosure buttons, and one coordinated open entry per navigation root. Include shared floating presentation. Preserve native navigation, logical Tab order, accessible panel relationships, retained child state, and initial server links for the navigation's own links.

Target framework-independent state in the existing @ariakit/components package, React rendering in @ariakit/react-components, and public React exports in @ariakit/react, following existing family entry points and store conventions. Do not create a new package or promise simultaneous Solid support. Keep the core store DOM-free so a later Solid port is mechanical. React 17, 18, and 19 remain the supported React range; React 17 needs the existing explicit-ID route for stable initial server relationships.

examples/menubar-navigation migrates to this family as part of the work, and #6992 closes on that basis. Its existing browser tests define the behaviour the migration must preserve, but they assert through menu ARIA roles, so none of them transfer unchanged and all are rewritten against the new family's native structure. The existing suite also omits the wraparound sequence and the touch and modifier cases, so those are new coverage rather than inherited.

Non-goals

This is not an application-menu tree, router, automatic URL matcher, mobile drawer, full no-JavaScript disclosure, or replacement for existing Menu/Menubar. Multiple simultaneously open top-level entries are outside the root model. Unhosted inline Content, a separate NavigationMenuViewport, viewport or inline mode props, public per-item stores, Item geometry overrides, and a new focus-strategy enum are outside v1. There is no new same-focus reopening shortcut on links. NavigationMenuHoverTrigger and NavigationMenuAnchor are outside v1; they may be considered in the future, but no later release is promised.

Item-local floating presentation is deferred out of v1 by D9 as amended. Panel bodies inside initial server HTML are no longer promised; see the server section.

The separate Composite focus/scroll defect in #7360 was fixed independently in bf64034 and shipped in @ariakit/[email protected]. It is not re-litigated here, and its existing regression must survive the migration.

Confirmed decision record

D5 is retired, without an accepted answer. It compared ways to extend Menubar and became inapplicable under D1. Do not reuse its identifier. No public-policy decision remains unanswered in this record.

Amendments to the 2026-08-31 body

Three sentences in the original body were proved false by reproductions run against the settled decisions. Each is replaced below and in its section.

A fourth claim in the original body is withdrawn as too strong rather than false. The Escape suppression concern about a resting pointer does not apply: hover intent is a module-global flag that requires real pointer movement, and a keydown resets it, so an accepted Escape leaves the panel closed while the pointer rests. Suppression is scoped to focus reopening only.

Implementation base and override contract

D15 fixes the base: the family composes Menu and Menubar. That decision carries a fixed set of overrides, and the mechanism for applying them is itself part of the contract.

Removing inherited ARIA. NavigationMenu parts call the Menu and Menubar use* hooks and delete the overridden keys from the returned props object before createElement, following the existing destructure of aria-labelledby out of the menu list hook in menu.tsx. Passing undefined for these props is defined by forwardRef to mean "omitted" and must not be used as a removal mechanism. Passing the value down through a use* hook is also invalid, because an intermediate strip lets a lower layer re-apply its own default: verified, a menu hook given role: undefined returned role="dialog" and its button returned aria-haspopup="dialog". composite={false} is not an option either, because the flag that suppresses the role also short-circuits the composite and destroys the traversal D6 depends on.

The override set. Roles on the menubar, list, item, button and the dialog underneath. aria-orientation. aria-haspopup, together with hideOnClick={false} wherever a disclosure sits inside a panel, because hideOnClick is keyed on aria-haspopup. Typeahead on both the primary and the panel. Page keys through moveOnKeyPress. Roving tabindex through tabbable on every primary, set internally and never exposed, with virtualFocus kept off because tabbable has no effect under it. The menu button's Enter/Space autofocus. The Escape wrapper. preserveTabOrderAnchor, which otherwise defaults to the disclosure element and falls back to the anchor element. The outside-interaction region. aria-controls and aria-labelledby, re-emitted owner-scoped.

What the base does not provide. Menu and Menubar keep part of their cross-entry coordination in the DOM, reading aria-expanded and aria-controls back off elements. Those two attributes survive here, re-emitted owner-scoped, so most of that path keeps working. The only part that depends on a removed attribute is the final [role=menuitem][aria-expanded=true] lookup inside menuHasFocus, which fires only for a disclosure nested inside an open panel, a composition v1 does not have. This was measured: on the current example, removing every menu role and aria-haspopup from the DOM before each interaction produced behaviour identical to the baseline. The family still owns entry switching against openId rather than relying on the inherited path.

Two defects in Menu are tracked separately, both reproduced against the published release with public API only. #7410 blocks the vertical half of D16. #7409 blocks the rich-nested-widget guarantee in both orientations, because in a horizontal menubar it takes Left/Right away from a focused text field inside an open panel. Both ship as Menu bug fixes in the same release.

Public parts and ownership

The following names describe the target API, not exports available in the inspected release. Reuse Ariakit's existing native props, polymorphic render, ref merging, store setters, event types, and package boundaries.

createNavigationMenuStore is the framework-independent factory and lives behind an @ariakit/components subpath export, following every other family. It is not a @ariakit/react export.

arrowNavigation, orientation, rtl and focusLoop belong to the root Provider/store, so detached parts share the same policy. showTimeout and hideTimeout also belong to the root; preserve explicit zero and existing Hovercard delay defaulting. The target example can explicitly use 100 ms show and 250 ms hide delays; these example values are not measured universal recommendations. Do not add a v1 focus-opening opt-out that can remove the selected split entry's keyboard route.

Keep shift, gutter, portal/wrapper options, and other DOM geometry on the actual Popover surface. Placement follows the existing surface-owner store setting, defaulted from orientation and rtl as described in the keyboard section, with an explicit author placement still winning. Do not add Item placement or offset overrides. For the shared host, derive per-entry values from mountedId, not from openId and not from a pending or stale request: openId flips to the next value at the instant an exit begins, while the outgoing panel is still on screen.

The associated NavigationMenuItem element supplies the positioning rectangle in v1. Disabling Item hover does not change that rectangle. Do not substitute the disclosure button or primary control as a positioning fallback. A detached Content resolves its Item through the same root and itemId; an Item element that is not attached yet is pending, not a reason to borrow another control's rectangle. This differs from existing Popover's disclosure fallback.

D12 still keeps placement and offsets on the positioned surface and its owner store. Item supplies the reference rectangle, not placement or offset overrides. The logical Tab-order anchor remains the primary link, or primary button in a button-only entry; the family passes it explicitly as preserveTabOrderAnchor so a split entry does not inherit Popover's disclosure-first Tab anchor.

Shared composition

The examples use the future family named exports from @ariakit/react. The shared host is outside Item scope and inside the same navigation root. Ordinary lists supply the panel's native structure.

function PrimaryNavigation() {
  const prefix = React.useId();
  const servicesId = prefix + "-services";
  const blogId = prefix + "-blog";
  const [openId, setOpenId] = React.useState<string | null>(null);
  // Every option goes on the store the application owns. A `store` prop on a
  // Provider is a sync source, so options passed there would land on a second,
  // derived store instead of this one.
  const navigation = useNavigationMenuStore({
    openId,
    setOpenId,
    placement: "bottom-start",
    showTimeout: 100,
    hideTimeout: 250,
  });
  // Derive surface settings from the mounted entry, not from openId, so the
  // surface does not move while an outgoing panel is still animating out.
  const mountedId = useStoreState(navigation, "mountedId");
  const shift = mountedId === servicesId ? -96 : mountedId === blogId ? -192 : 0;

  return (
    <NavigationMenuProvider store={navigation}>
      <NavigationMenu aria-label="Primary">
        <ul>
          <NavigationMenuItem id={servicesId} className="navigation-entry">
            <NavigationMenuLink href="/services">Services</NavigationMenuLink>
            <NavigationMenuButton aria-label="Services links">
              <NavigationMenuButtonArrow />
            </NavigationMenuButton>
            <NavigationMenuContent>
              <ul>
                <li>
                  <NavigationMenuLink href="/services/web">
                    Web Development
                  </NavigationMenuLink>
                </li>
              </ul>
            </NavigationMenuContent>
          </NavigationMenuItem>
          <NavigationMenuItem id={blogId}>
            <NavigationMenuButton>Blog</NavigationMenuButton>
            <NavigationMenuContent>
              <ul>
                <li>
                  <NavigationMenuLink href="/blog/latest">
                    Latest posts
                  </NavigationMenuLink>
                </li>
              </ul>
            </NavigationMenuContent>
          </NavigationMenuItem>
          <li><NavigationMenuLink href="/contact">Contact</NavigationMenuLink></li>
        </ul>
        <NavigationMenuPopover gutter={8} shift={shift}>
          <NavigationMenuArrow />
        </NavigationMenuPopover>
      </NavigationMenu>
    </NavigationMenuProvider>
  );
}

The real button exposes aria-expanded, and the family emits aria-controls on it pointing at that entry's own panel. Both are computed during render from accepted root state and the per-entry panel id rather than read back from a shared content element, so exactly one element in the navigation carries aria-controls at any moment and it is the entry that owns the mounted panel. The shared panel's aria-labelledby points at that same entry's primary. The category link retains href and optional aria-current; it does not copy the button's disclosure attributes. Keep the link and button as siblings. A shared focus outline can surround their header group while actual focus remains on the link. Do not make the wrapper a third button or hide the secondary button from assistive technology; only its decorative graphic may be hidden.

Detached association