[menu] Add highlightItem('first' | 'last' | 'none') imperative action

[chsmc-ant]

When a menu is opened programmatically (via controlled open, or MenuHandle.open(), or onOpenChange(true) from a custom interaction that isn't one of Menu.Trigger's built-in open keys), useListNavigation leaves activeIndex as null. This is correct for pointer-driven opens, but for custom keyboard shortcuts it means every item renders with tabindex="-1" and FloatingFocusManager moves focus to the popup container rather than the first item — the user then has to press ↓ once more before arrow navigation works.

This PR adds an imperative highlightItem(target: 'first' | 'last' | 'none') action so callers can ask the menu to highlight an item once it opens:

• Menu.Root actionsRef — alongside unmount / close:

  const actionsRef = React.useRef<Menu.Root.Actions>(null);
  
  function onCustomKeyDown(event: React.KeyboardEvent) {
    if (event.key === 'ArrowRight') {
      setOpen(true);
      actionsRef.current?.highlightItem('first');
    }
  }
  
  <Menu.Root open={open} onOpenChange={setOpen} actionsRef={actionsRef}>

• MenuHandle.open(triggerId, highlightItem?) — same values as a second parameter:

  handle.open('my-trigger', 'first');

The requested target is stored as pendingHighlightItem on MenuStore and resolved inside useListNavigation's initial-sync layout effect once the list is populated, using getMinListIndex / getMaxListIndex so hidden items are skipped — the same logic used for the built-in focusItemOnOpen path. useListNavigation then moves DOM focus to the resolved item (for Menu; virtual-focus consumers like Combobox would only update activeIndex).

A Menu.Root.HighlightItem type alias is exported for the 'first' | 'last' | 'none' union.

Preview: https://deploy-preview-4815--base-ui.netlify.app/react/components/menu#controlled-mode-with-multiple-triggers

---

Earlier revisions exposed a raw setActiveIndex(index) setter and then a focusItem() action; reworked per review to use highlightItem() with directional targets and to cover MenuHandle.open as well.

[code-infra-dashboard]

Bundle size

Bundle	Parsed size	Gzip size
@base-ui/react	🔺+684B(+0.15%)	🔺+171B(+0.12%)

Details of bundle changes

Performance

Total duration: 1,138.58 ms +46.42 ms^(+4.3%) | Renders: 50 ⁽⁺⁰⁾ | Paint: 1,744.43 ms +80.65 ms^(+4.8%)

No significant changes — details

---

Check out the code infra dashboard for more information about this PR.

[netlify]

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	c555d20
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/6a0eee462861db000804f141
😎 Deploy Preview	https://deploy-preview-4815--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[oliviertassinari]

To help the team a bit (and your team on Claude), here is a reproduction that seems to reproduce the problem: https://stackblitz.com/edit/va1fcbzq?file=src%2FApp.tsx (repro based on this demo):

Screen.Recording.2026-05-13.at.00.37.47.mov

---

It's not clear that this should be solved with a new API; this feels like a bug: I would expect the same behavior regardless of how the menu is open: with a trigger, with the open prop.

For example, in https://mui.com/material-ui/react-menu/, the focus is placed on the first menu item when the menu opens (with the keyboard) but the behavior can be configured with a prop.

Let's wait for team inputs.

[chsmc-ant]

Thanks @oliviertassinari and good call! I opened #4816 as well so we can compare this approach to that one. Will defer to the team on which they'd prefer.

[pkg-pr-new]

• base-ui-tanstack-start

• vite-css-base-ui-example

  pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/react@4815
  

  pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/utils@4815
  

commit: c555d20

[atomiks]

Thanks for the PR @chsmc-ant

Makes sense as controlled-opens are assumed to always be pointer-driven, but a keyboard-driven controlled open is also valid in which case the highlight should be set on the first item.

An imperative action also makes more sense than a prop like autoHighlight (which Autocomplete has) since this is a one-shot/event-driven action that probably shouldn't need state.

The only issue is naming: setActiveIndex is quite broad and "active" is more so an internal name as we use highlighted or focus publicly.

I'm also not sure if exposing the index is a good idea, because 1) disabled items should be skipped on initial open, which should pass through the internal logic to skip them, and 2) it's likely hard to keep track of which index is the last item if the controlled open is an ArrowUp for example.

Possible alternative: .focusItem('first' | 'last' | 'none') or .focusItem('start' | 'end' | 'none')

cc: @colmtuite

---

Side note: in case you need this behavior before release, this technically already works, if hacky:

firstItem.focus();
// or firstItem.dispatchEvent(new MouseEvent('mousemove', { bubbles: true }))

[michaldudak]

We have another imperative API that has the same issue: MenuHandle.open. Whatever solution we land on for the actionsRef, we should also apply it there. I like @atomiks idea with .focusItem('first' | 'last' | 'none'). We could add an optional parameter to the handle's open method: open(triggerId: string, focusItem?: 'first' | 'last' | 'none').

[chsmc-ant]

Thanks for the feedback @atomiks @michaldudak — pushed 974094c which:

• Replaces setActiveIndex(index) with focusItem('first' | 'last' | 'none') on actionsRef, resolved via getMinListIndex/getMaxListIndex so hidden items are skipped.
• Adds the same option as a second parameter to MenuHandle.open(triggerId, focusItem?).
• Exports Menu.Root.FocusItem for the union type.

PR description updated to match. Happy to bikeshed 'first' | 'last' vs 'start' | 'end' if there's a preference.

[atomiks]

Folded this into useListNavigation as it removes the duplicate effect, and AriaCombobox will likely want this behavior as well: #4745

[atomiks]

I think .highlightItem() is likely a better term for this, because the public API is about the highlighted state, even though focus is in sync with it. And AriaCombobox doesn't use DOM focus, so highlight makes more sense if this is to be added there — @michaldudak

[chsmc-ant]

thanks @atomiks happy to go ahead and implement that rename if you think it's the right approach

[chsmc-ant]

Renamed to highlightItem in f4aa2a8 — covers actionsRef.highlightItem(), MenuHandle.open(triggerId, highlightItem?), the exported Menu.Root.HighlightItem type, and the internal pendingHighlightItem plumbing through MenuStore / useListNavigation. Left the pre-existing internal focusItem/resolveFocusItem helpers in useListNavigation alone since those are about DOM focus and shared with the focusItemOnOpen path.

[oliviertassinari]

I wonder how we will fix this demo https://base-ui.com/react/components/menu#controlled-mode-with-multiple-triggers later on. I guess we will add something like:

<button
  type="button"
  className={styles.Button}
  onClick={(event) => {
    // Detect if the interaction was explicitly driven by a keyboard. Unless we need isVirtualClick().
    const isKeyboard = event.detail === 0;
    setOpen(true);
    actionsRef.current!.highlightItem(isKeyboard ? 'first' : null);

Not fully self managed by the popover (testing for :focus-visible), but this stays kind of simple.

[atomiks]

This looks right now, thanks for the contribution @chsmc-ant

I ran Codex & Claude reviews on it and they both found some issues which I hardened in the follow up commits.

Something intentional (that they reported): I removed the waitForListPopulatedFrame as that was unnecessary on top of the queueMicrotask based on all tests:

CompositeList does the index reconciliation, then useCompositeListItem writes the actual DOM node into listRef.current[index] once the item gets its resolved index. That can require one extra layout-effect/update turn for composed items, so the PR waits with queueMicrotask before deciding the list is empty.

It was from the floating-ui fork which added an extra rAF just as a precaution, but only the microtask is needed

---

Unrelated to this PR, but needs to be fixed as well: there's a bug where if you mouse into the menu that was controlled-open by a different trigger, it closes upon mouseleave unexpectedly, because the hover hook requires a click on its trigger to block the close on mouseleave. I'll fix it in a new PR

[chsmc-ant]

Thanks @atomiks I think the failing test is flake/unrelated, is there anything else I need to do before we can merge this?

[aarongarciah]

Unrelated to this PR

@dav-is something to improve in the types.md file generation? close and highlightItem are bullets in the original code (see https://github.com/mui/base-ui/pull/4815/changes#diff-0c9aa23d488587208914fe2b3474310cf0586456d23b0cd370e448b2a5ddc7dfR639-R640). I we can't use bullets inside the markdown table (I've seen some MD renderers allowing to use them when using <br> for new lines), we could add a space at least.

[aarongarciah]

Thanks @atomiks I think the failing test is flake/unrelated, is there anything else I need to do before we can merge this?

@chsmc-ant yes, we have a flacky test. I've re-run it and now it's all green.