NavigationTree: selectedRoute lookup stops at the first href match — are duplicate hrefs (pinned shortcuts) meant to be supported?

[BMCwebdev]

NavigationTree (react-aria-components 1.22.1, alpha) matches selectedRoute against each item's href. The per-item isCurrent handles duplicates correctly, but the two lookups that derive state from the match stop at the first href match in collection order, so a repeated destination (a "pinned" shortcut, a "recent" list, a footer repeat) placed before the real one captures the focus sync and empties the ancestor set.

Question: are duplicate hrefs meant to be supported by NavigationTree? If yes, I'd like to propose making the two lookups duplicate-aware; if no, a documented first-match rule (and maybe a dev warning when a route matches more than one item) would save consumers the debugging.

What happens

With a pinned copy of "Payments" in a section above the hierarchy that also contains "Payments" under Grants › Awards, and selectedRoute pointing at it:

• both "Payments" rows get aria-current="page" and data-current (correct);
• no row gets data-current-ancestor (the pinned copy has no ancestors, and the lookup never reaches the nested copy);
• Tab enters the tree on the pinned link, never on a row inside the hierarchy.

Remove the pinned section and "Grants" and "Awards" carry data-current-ancestor as expected. The reverse holds too: with the route on "Applications" (inside the hierarchy) the flag lands on "Grants"; add a pinned copy of "Applications" above and it is gone again.

Composition

import {
  Link, NavigationTree, NavigationTreeItem, NavigationTreeItemContent, NavigationTreeSection,
} from 'react-aria-components';

const Item = ({ id, href, label }) => (
  <NavigationTreeItem id={id} href={href} textValue={label}>
    <NavigationTreeItemContent><Link>{label}</Link></NavigationTreeItemContent>
  </NavigationTreeItem>
);

<NavigationTree
  aria-label="Main"
  selectedRoute="#/grants/awards/payments"
  defaultExpandedKeys={['grants', 'awards']}>
  <NavigationTreeSection aria-label="Pinned">
    <Item id="pinned-payments" href="#/grants/awards/payments" label="Payments" />
  </NavigationTreeSection>
  <NavigationTreeSection aria-label="Navigation">
    <NavigationTreeItem id="grants" textValue="Grants">
      <NavigationTreeItemContent>Grants</NavigationTreeItemContent>
      <NavigationTreeItem id="awards" textValue="Awards">
        <NavigationTreeItemContent>Awards</NavigationTreeItemContent>
        <Item id="payments" href="#/grants/awards/payments" label="Payments" />
      </NavigationTreeItem>
    </NavigationTreeItem>
  </NavigationTreeSection>
</NavigationTree>

Steps: render; read aria-current, data-current and data-current-ancestor across the rows; Tab into the tree; remove the "Pinned" section and read data-current-ancestor again.

Source (tag react-aria-components@1.22.1; identical on main today)

• findKeyForRoute returns the first match: https://github.com/adobe/react-spectrum/blob/react-aria-components@1.22.1/packages/react-aria-components/src/NavigationTree.tsx#L313-L320
• useRouteFocusSync sets the focused key from it: https://github.com/adobe/react-spectrum/blob/react-aria-components@1.22.1/packages/react-aria-components/src/NavigationTree.tsx#L344-L362
• getSelectedAncestors walks up from the same single match and caches per collection: https://github.com/adobe/react-spectrum/blob/react-aria-components@1.22.1/packages/react-aria-components/src/NavigationTree.tsx#L371-L386
• per-item isCurrent is independent of the lookup: https://github.com/adobe/react-spectrum/blob/react-aria-components@1.22.1/packages/react-aria-components/src/NavigationTree.tsx#L215-L216

(#10650 moves closestVisibleKey into utils for Tree/Table; it does not change which key the route lookup picks, so it is adjacent rather than overlapping.)

Proposed direction, if duplicates are in scope

Collect every key whose href matches. getSelectedAncestors returns the union of their ancestor chains. useRouteFocusSync prefers the deepest match, or the first match inside an expanded branch, over the first in collection order. isCurrent already needs no change.

Context

Bonterra's Stitch design system. Measured while evaluating NavigationTree for an app side navigation whose design has a pinned section above the hierarchy. Chromium 147 via Playwright 1.59 (real key presses) for focus entry; jsdom for the attribute assertions. react-aria-components 1.22.1 / react-aria 3.53.1 / react-stately 3.51.0, React 19.2.3.

[FelixFangX]

I can reproduce this with your composition on react-aria-components 1.22.1 (jsdom). With the pinned section first, both Payments rows get data-current but neither Grants nor Awards gets data-current-ancestor. Move the pinned section after the hierarchy and the ancestors come back. That matches your reading of findKeyForRoute: it returns the first key in collection order, and both getSelectedAncestors and useRouteFocusSync start from that one key.

Whether duplicates are in scope is for the team, but in the meantime, rendering the pinned section as its own NavigationTree gets you the right result without touching the hierarchy:

<nav aria-label="Main">
  <NavigationTree aria-label="Pinned" selectedRoute={route}>
    <Item id="pinned-payments" href="#/grants/awards/payments" label="Payments" />
  </NavigationTree>
  <NavigationTree aria-label="Navigation" selectedRoute={route} defaultExpandedKeys={['grants', 'awards']}>
    {/* Grants › Awards › Payments */}
  </NavigationTree>
</nav>

With that I get data-current on both Payments rows and data-current-ancestor on Grants and Awards. Each tree runs its own lookup, so the pinned copy can't take over the main tree's focus sync. The trade-off is two tab stops and arrow keys that don't cross between the pinned list and the hierarchy, which may actually be what you want for a pinned area. I only checked the attributes in jsdom, not Tab behavior in a real browser.

+1 on the dev warning if first-match stays the rule. It took me a minute to spot even with your write-up.

[BMCwebdev]

Thanks for checking it, and for the two-tree workaround. The cost you name is the one we measured: with one tree the whole nav is two Tab stops (the switcher and the tree); the pinned list as its own tree adds a third, and arrow keys stop at the seam. For a pinned area that may be acceptable; for a "recent" list or a footer repeat less so. The question for the team stands: duplicate-aware lookups, or a documented first-match rule with a warning.

[snowystinger]

Thanks for the issue. I'm not sure how we'd support multiple being selected even if they are the same "page". The docs for aria-current https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-current#description

Only mark one element in a set of elements as current with aria-current.

I think I'd recommend moving "pinned" items out of their normal locations and putting them into the pinned section only instead.

Native Mac Finder also only highlights one entry, not both if you have something in both Locations and Favourites.