From f298aa27599da0a7c3c981ceffecc491f69e9ccf Mon Sep 17 00:00:00 2001
From: Matt Obee <mattobee@github.com>
Date: Thu, 3 Sep 2026 11:47:56 +0100
Subject: [PATCH 1/6] Add linked NavList sub-nav parents

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 6f4333c6-7280-4a91-b0a0-eefc06ff8b70
---
 .changeset/lazy-linked-subnav.md              |   5 +
 packages/react/src/NavList/NavList.docs.json  |   8 +-
 .../src/NavList/NavList.features.stories.tsx  |  17 +++
 packages/react/src/NavList/NavList.module.css |  20 ++++
 packages/react/src/NavList/NavList.test.tsx   |  69 +++++++++++
 packages/react/src/NavList/NavList.tsx        | 110 ++++++++++++++----
 6 files changed, 207 insertions(+), 22 deletions(-)
 create mode 100644 .changeset/lazy-linked-subnav.md

diff --git a/.changeset/lazy-linked-subnav.md b/.changeset/lazy-linked-subnav.md
new file mode 100644
index 00000000000..c2ae5e0c8bc
--- /dev/null
+++ b/.changeset/lazy-linked-subnav.md
@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+NavList: Support linked sub-nav parent items with a separate toggle
diff --git a/packages/react/src/NavList/NavList.docs.json b/packages/react/src/NavList/NavList.docs.json
index 72258bed5f1..3376dd09627 100644
--- a/packages/react/src/NavList/NavList.docs.json
+++ b/packages/react/src/NavList/NavList.docs.json
@@ -15,6 +15,7 @@
     {"id": "components-navlist-features--with-group-expand"},
     {"id": "components-navlist-features--with-group-heading-links"},
     {"id": "components-navlist-features--with-inactive-items"},
+    {"id": "components-navlist-features--with-linked-sub-nav-parent"},
     {"id": "components-navlist-features--with-nested-sub-items"},
     {"id": "components-navlist-features--with-next-js-link"},
     {"id": "components-navlist-features--with-react-router-link"},
@@ -95,7 +96,7 @@
           "name": "href",
           "type": "string",
           "defaultValue": "",
-          "description": "The URL that the item navigates to. `href` is passed to the underlying `<a>` element. If `as` is specified, the component may need different props. If the item contains a sub-nav, the item is rendered as a `<button>` and `href` is ignored."
+          "description": "The URL that the item navigates to. `href` is passed to the underlying `<a>` element. If `as` is specified, the component may need different props. If the item contains a sub-nav, the item is rendered as a `<button>` and `href` is ignored unless `subNavToggleLabel` is also set."
         },
         {
           "name": "aria-current",
@@ -108,6 +109,11 @@
           "type": "boolean",
           "description": "The open state of the item when it is initially rendered if the item has a SubNav."
         },
+        {
+          "name": "subNavToggleLabel",
+          "type": "string",
+          "description": "Renders an item with a SubNav as a link with a separate toggle button. The value is used as the toggle button's accessible name."
+        },
         {
           "name": "inactiveText",
           "type": "string",
diff --git a/packages/react/src/NavList/NavList.features.stories.tsx b/packages/react/src/NavList/NavList.features.stories.tsx
index b9488ea1fae..0b8bbcbe497 100644
--- a/packages/react/src/NavList/NavList.features.stories.tsx
+++ b/packages/react/src/NavList/NavList.features.stories.tsx
@@ -53,6 +53,23 @@ export const WithSubItems: StoryFn = () => (
   </PageLayout>
 )
 
+export const WithLinkedSubNavParent: StoryFn = () => (
+  <PageLayout>
+    <PageLayout.Pane position="start">
+      <NavList>
+        <NavList.Item href="#" subNavToggleLabel="Toggle overview pages">
+          Overview
+          <NavList.SubNav>
+            <NavList.Item href="#">Review requested</NavList.Item>
+            <NavList.Item href="#">Your drafts</NavList.Item>
+          </NavList.SubNav>
+        </NavList.Item>
+      </NavList>
+    </PageLayout.Pane>
+    <PageLayout.Content></PageLayout.Content>
+  </PageLayout>
+)
+
 export const WithNestedSubItems: StoryFn = () => (
   <PageLayout>
     <PageLayout.Pane position="start">
diff --git a/packages/react/src/NavList/NavList.module.css b/packages/react/src/NavList/NavList.module.css
index 93dbb6674eb..e610968bc58 100644
--- a/packages/react/src/NavList/NavList.module.css
+++ b/packages/react/src/NavList/NavList.module.css
@@ -12,3 +12,23 @@
 .GroupHeading > a:hover {
   text-decoration: underline;
 }
+
+.SubNavToggle > [aria-expanded='true'] svg {
+  transform: scaleY(-1);
+}
+
+.LinkedSubNavItem[data-component='ActionList.Item'] {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) min-content;
+
+  & > [data-component='ActionList.TrailingAction'] {
+    grid-area: auto;
+    grid-row: 1;
+    grid-column: 2;
+  }
+
+  & > [data-component='NavList.SubNav'] {
+    grid-row: 2;
+    grid-column: 1 / -1;
+  }
+}
diff --git a/packages/react/src/NavList/NavList.test.tsx b/packages/react/src/NavList/NavList.test.tsx
index 6fd762ea3f4..5389e508347 100644
--- a/packages/react/src/NavList/NavList.test.tsx
+++ b/packages/react/src/NavList/NavList.test.tsx
@@ -271,6 +271,75 @@ describe('NavList.Item with NavList.SubNav', () => {
     expect(queryByRole('list', {name: 'Item 2'})).toBeNull()
   })
 
+  it('supports a link with a separate SubNav toggle', () => {
+    const {getByRole, queryByRole} = render(
+      <NavList>
+        <NavList.Item
+          href="/overview"
+          aria-current="page"
+          subNavToggleLabel="Toggle overview pages"
+          onClick={event => event.preventDefault()}
+        >
+          Overview
+          <NavList.SubNav>
+            <NavList.Item href="/overview/review-requested">Review requested</NavList.Item>
+          </NavList.SubNav>
+        </NavList.Item>
+      </NavList>,
+    )
+    const link = getByRole('link', {name: 'Overview'})
+    const toggle = getByRole('button', {name: 'Toggle overview pages'})
+
+    expect(link).toHaveAttribute('href', '/overview')
+    expect(link).toHaveAttribute('aria-current', 'page')
+    expect(toggle).toHaveAttribute('aria-expanded', 'false')
+    expect(queryByRole('list', {name: 'Overview'})).toBeNull()
+
+    fireEvent.click(link)
+    expect(toggle).toHaveAttribute('aria-expanded', 'false')
+
+    fireEvent.click(toggle)
+    expect(toggle).toHaveAttribute('aria-expanded', 'true')
+    expect(getByRole('list', {name: 'Overview'})).toBeVisible()
+  })
+
+  it('forwards custom link props when using a separate SubNav toggle', () => {
+    const {getByRole} = render(
+      <NavList>
+        <NavList.Item as={ReactRouterLikeLink} to="/overview" subNavToggleLabel="Toggle overview pages">
+          Overview
+          <NavList.SubNav>
+            <NavList.Item href="/overview/review-requested">Review requested</NavList.Item>
+          </NavList.SubNav>
+        </NavList.Item>
+      </NavList>,
+    )
+
+    expect(getByRole('link', {name: 'Overview'})).toHaveAttribute('href', '/overview')
+  })
+
+  it('requires a link target when using a separate SubNav toggle', () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => null)
+
+    const {getByRole, queryByRole} = render(
+      <NavList>
+        <NavList.Item subNavToggleLabel="Toggle overview pages">
+          Overview
+          <NavList.SubNav>
+            <NavList.Item href="/overview/review-requested">Review requested</NavList.Item>
+          </NavList.SubNav>
+        </NavList.Item>
+      </NavList>,
+    )
+
+    expect(getByRole('button', {name: 'Overview'})).toBeInTheDocument()
+    expect(queryByRole('link', {name: 'Overview'})).toBeNull()
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'NavList.Item must have an href or custom link component to use subNavToggleLabel.',
+    )
+    consoleSpy.mockRestore()
+  })
+
   it('prevents more than 4 levels of nested SubNavs', () => {
     const consoleSpy = vi
       .spyOn(console, 'error')
diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index db954644f45..6157a822d51 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -135,6 +135,7 @@ export type NavListItemProps<As extends React.ElementType = React.ElementType> =
     children: React.ReactNode
     defaultOpen?: boolean
     href?: string
+    subNavToggleLabel?: string
     'aria-current'?: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false' | boolean
     inactiveText?: string
     tooltipText?: string
@@ -143,10 +144,19 @@ export type NavListItemProps<As extends React.ElementType = React.ElementType> =
 
 const ItemComponent = fixedForwardRef(
   <As extends React.ElementType = 'a'>(
-    {'aria-current': ariaCurrent, children, defaultOpen, tooltipText, as: Component, ...props}: NavListItemProps<As>,
+    {
+      'aria-current': ariaCurrent,
+      children,
+      defaultOpen,
+      subNavToggleLabel,
+      tooltipText,
+      as: Component,
+      ...props
+    }: NavListItemProps<As>,
     ref: React.ForwardedRef<unknown>,
   ) => {
     const {depth} = React.useContext(SubNavContext)
+    const hasLinkTarget = Boolean(props.href || (Component && Component !== 'a'))
 
     // Extract SubNav from children; useSlots also returns `rest` with TrailingAction filtered out.
     const [slots, childrenWithoutSubNavOrTrailingAction] = useSlots(children, {
@@ -159,6 +169,10 @@ const ItemComponent = fixedForwardRef(
       // eslint-disable-next-line no-console
       console.error('NavList.Item must have a NavList.SubNav to use defaultOpen.')
 
+    if (subNavToggleLabel && !hasLinkTarget)
+      // eslint-disable-next-line no-console
+      console.error('NavList.Item must have an href or custom link component to use subNavToggleLabel.')
+
     // Render ItemWithSubNav if SubNav is present
     if (subNav && isValidElement(subNav)) {
       return (
@@ -166,8 +180,16 @@ const ItemComponent = fixedForwardRef(
           subNav={subNav}
           depth={depth}
           defaultOpen={defaultOpen}
+          subNavToggleLabel={hasLinkTarget ? subNavToggleLabel : undefined}
           tooltipText={tooltipText}
+          ariaCurrent={ariaCurrent}
           style={{'--subitem-depth': depth} as React.CSSProperties}
+          linkProps={{
+            ref,
+            as: Component,
+            'aria-current': ariaCurrent,
+            ...props,
+          }}
         >
           {childrenWithoutSubNavOrTrailingAction}
         </ItemWithSubNav>
@@ -206,8 +228,11 @@ type ItemWithSubNavProps = {
   subNav: React.ReactNode
   depth: number
   defaultOpen?: boolean
+  subNavToggleLabel?: string
   tooltipText?: string
+  ariaCurrent?: NavListItemProps['aria-current']
   style: React.CSSProperties
+  linkProps: Record<string, unknown>
 }
 
 const ItemWithSubNavContext = React.createContext<{buttonId: string; subNavId: string; isOpen: boolean}>({
@@ -238,7 +263,17 @@ function hasCurrentNavItem(node: React.ReactNode): boolean {
   return React.Children.toArray(node.props.children).some(hasCurrentNavItem)
 }
 
-function ItemWithSubNav({children, subNav, depth: _depth, defaultOpen, tooltipText, style}: ItemWithSubNavProps) {
+function ItemWithSubNav({
+  children,
+  subNav,
+  depth: _depth,
+  defaultOpen,
+  subNavToggleLabel,
+  tooltipText,
+  ariaCurrent,
+  style,
+  linkProps,
+}: ItemWithSubNavProps) {
   const buttonId = useId()
   const subNavId = useId()
 
@@ -262,26 +297,58 @@ function ItemWithSubNav({children, subNav, depth: _depth, defaultOpen, tooltipTe
     }
   }, [subNav, buttonId])
 
+  const subItem = (
+    <SubItem>
+      {/* eslint-disable-next-line @typescript-eslint/no-explicit-any */}
+      {React.cloneElement(subNav as React.ReactElement<any>, {
+        ref: subNavRef,
+      })}
+    </SubItem>
+  )
+
+  const toggleSubNav = () => setIsOpen(open => !open)
+
   return (
     <ItemWithSubNavContext.Provider value={{buttonId, subNavId, isOpen}}>
-      <ActionList.Item
-        id={buttonId}
-        aria-expanded={isOpen}
-        aria-controls={subNavId}
-        active={!isOpen && containsCurrentItem}
-        onSelect={() => setIsOpen(open => !open)}
-        style={style}
-        data-component="NavList.Item"
-        _PrivateTooltipText={tooltipText}
-      >
-        {children}
-        {/* What happens if the user provides a TrailingVisual? */}
-        <ActionList.TrailingVisual>
-          <ChevronDownIcon className={classes.ExpandIcon} />
-        </ActionList.TrailingVisual>
-        {/* eslint-disable-next-line @typescript-eslint/no-explicit-any */}
-        <SubItem>{React.cloneElement(subNav as React.ReactElement<any>, {ref: subNavRef})}</SubItem>
-      </ActionList.Item>
+      {subNavToggleLabel ? (
+        <ActionList.LinkItem
+          {...linkProps}
+          id={buttonId}
+          active={(Boolean(ariaCurrent) && ariaCurrent !== 'false') || (!isOpen && containsCurrentItem)}
+          className={clsx(linkProps.className as string | undefined, navListClasses.LinkedSubNavItem)}
+          style={style}
+          data-component="NavList.Item"
+          _PrivateTooltipText={tooltipText}
+        >
+          {children}
+          <ActionList.TrailingAction
+            aria-controls={subNavId}
+            aria-expanded={isOpen}
+            className={navListClasses.SubNavToggle}
+            icon={ChevronDownIcon}
+            label={subNavToggleLabel}
+            onClick={toggleSubNav}
+          />
+          {subItem}
+        </ActionList.LinkItem>
+      ) : (
+        <ActionList.Item
+          id={buttonId}
+          aria-expanded={isOpen}
+          aria-controls={subNavId}
+          active={!isOpen && containsCurrentItem}
+          onSelect={toggleSubNav}
+          style={style}
+          data-component="NavList.Item"
+          _PrivateTooltipText={tooltipText}
+        >
+          {children}
+          <ActionList.TrailingVisual>
+            <ChevronDownIcon className={classes.ExpandIcon} />
+          </ActionList.TrailingVisual>
+          {subItem}
+        </ActionList.Item>
+      )}
     </ItemWithSubNavContext.Provider>
   )
 }
@@ -297,7 +364,7 @@ const SubNavContext = React.createContext<{depth: number}>({depth: 0})
 
 // NOTE: SubNav must be a direct child of an Item
 const SubNav = React.forwardRef<HTMLUListElement, NavListSubNavProps>(({children}, forwardedRef) => {
-  const {buttonId, subNavId} = React.useContext(ItemWithSubNavContext)
+  const {buttonId, subNavId, isOpen} = React.useContext(ItemWithSubNavContext)
   const {depth} = React.useContext(SubNavContext)
   if (!buttonId || !subNavId) {
     // eslint-disable-next-line no-console
@@ -317,6 +384,7 @@ const SubNav = React.forwardRef<HTMLUListElement, NavListSubNavProps>(({children
         className={classes.SubGroup}
         id={subNavId}
         aria-labelledby={buttonId}
+        hidden={!isOpen}
         ref={forwardedRef}
         data-component="NavList.SubNav"
       >

From 53bf646e216ecf72fce40e06f788bcd17d83730a Mon Sep 17 00:00:00 2001
From: Matt Obee <mattobee@github.com>
Date: Thu, 3 Sep 2026 12:10:22 +0100
Subject: [PATCH 2/6] Refine linked sub-nav implementation

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 6f4333c6-7280-4a91-b0a0-eefc06ff8b70
---
 packages/react/src/NavList/NavList.module.css | 25 +++--
 packages/react/src/NavList/NavList.test.tsx   | 42 ++++++--
 packages/react/src/NavList/NavList.tsx        | 96 ++++++++++++-------
 3 files changed, 109 insertions(+), 54 deletions(-)

diff --git a/packages/react/src/NavList/NavList.module.css b/packages/react/src/NavList/NavList.module.css
index e610968bc58..babef5120f2 100644
--- a/packages/react/src/NavList/NavList.module.css
+++ b/packages/react/src/NavList/NavList.module.css
@@ -13,22 +13,19 @@
   text-decoration: underline;
 }
 
-.SubNavToggle > [aria-expanded='true'] svg {
-  transform: scaleY(-1);
-}
-
-.LinkedSubNavItem[data-component='ActionList.Item'] {
+/* Match ActionList's attribute-selector specificity without depending on its DOM attributes. */
+.LinkedSubNavItem.LinkedSubNavItem {
   display: grid;
   grid-template-columns: minmax(0, 1fr) min-content;
+}
 
-  & > [data-component='ActionList.TrailingAction'] {
-    grid-area: auto;
-    grid-row: 1;
-    grid-column: 2;
-  }
+.SubNavToggle.SubNavToggle {
+  grid-area: auto;
+  grid-row: 1;
+  grid-column: 2;
+}
 
-  & > [data-component='NavList.SubNav'] {
-    grid-row: 2;
-    grid-column: 1 / -1;
-  }
+.LinkedSubNav.LinkedSubNav {
+  grid-row: 2;
+  grid-column: 1 / -1;
 }
diff --git a/packages/react/src/NavList/NavList.test.tsx b/packages/react/src/NavList/NavList.test.tsx
index 5389e508347..bd218e551b2 100644
--- a/packages/react/src/NavList/NavList.test.tsx
+++ b/packages/react/src/NavList/NavList.test.tsx
@@ -276,7 +276,10 @@ describe('NavList.Item with NavList.SubNav', () => {
       <NavList>
         <NavList.Item
           href="/overview"
+          id="overview-link"
           aria-current="page"
+          className="custom-class"
+          style={{color: 'red'}}
           subNavToggleLabel="Toggle overview pages"
           onClick={event => event.preventDefault()}
         >
@@ -291,7 +294,10 @@ describe('NavList.Item with NavList.SubNav', () => {
     const toggle = getByRole('button', {name: 'Toggle overview pages'})
 
     expect(link).toHaveAttribute('href', '/overview')
+    expect(link).toHaveAttribute('id', 'overview-link')
     expect(link).toHaveAttribute('aria-current', 'page')
+    expect(link).toHaveStyle({color: 'rgb(255, 0, 0)'})
+    expect(link.closest('li')).toHaveClass('custom-class')
     expect(toggle).toHaveAttribute('aria-expanded', 'false')
     expect(queryByRole('list', {name: 'Overview'})).toBeNull()
 
@@ -318,12 +324,12 @@ describe('NavList.Item with NavList.SubNav', () => {
     expect(getByRole('link', {name: 'Overview'})).toHaveAttribute('href', '/overview')
   })
 
-  it('requires a link target when using a separate SubNav toggle', () => {
-    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => null)
+  it('warns when a linked SubNav parent does not render an anchor', () => {
+    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => null)
 
-    const {getByRole, queryByRole} = render(
+    const {getByRole} = render(
       <NavList>
-        <NavList.Item subNavToggleLabel="Toggle overview pages">
+        <NavList.Item as="button" subNavToggleLabel="Toggle overview pages">
           Overview
           <NavList.SubNav>
             <NavList.Item href="/overview/review-requested">Review requested</NavList.Item>
@@ -333,9 +339,33 @@ describe('NavList.Item with NavList.SubNav', () => {
     )
 
     expect(getByRole('button', {name: 'Overview'})).toBeInTheDocument()
-    expect(queryByRole('link', {name: 'Overview'})).toBeNull()
     expect(consoleSpy).toHaveBeenCalledWith(
-      'NavList.Item must have an href or custom link component to use subNavToggleLabel.',
+      'Warning:',
+      'NavList.Item with subNavToggleLabel must render an anchor with an href.',
+    )
+    consoleSpy.mockRestore()
+  })
+
+  it('warns when a custom linked SubNav parent does not forward its ref', () => {
+    const CustomLink = React.forwardRef<HTMLAnchorElement, {children?: React.ReactNode; href?: string}>(
+      ({children}, _ref) => <div>{children}</div>,
+    )
+    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => null)
+
+    render(
+      <NavList>
+        <NavList.Item as={CustomLink} href="/overview" subNavToggleLabel="Toggle overview pages">
+          Overview
+          <NavList.SubNav>
+            <NavList.Item href="/overview/review-requested">Review requested</NavList.Item>
+          </NavList.SubNav>
+        </NavList.Item>
+      </NavList>,
+    )
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      'Warning:',
+      'NavList.Item with subNavToggleLabel must render an anchor with an href.',
     )
     consoleSpy.mockRestore()
   })
diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index 6157a822d51..2620b46bd15 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -1,4 +1,4 @@
-import {ChevronDownIcon, PlusIcon, type Icon} from '@primer/octicons-react'
+import {ChevronDownIcon, ChevronUpIcon, PlusIcon, type Icon} from '@primer/octicons-react'
 import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../utils/polymorphic'
 import React, {isValidElement} from 'react'
 import {clsx} from 'clsx'
@@ -23,6 +23,9 @@ import HeadingComponent from '../Heading'
 import visuallyHiddenClasses from '../_VisuallyHidden.module.css'
 import type {FCWithSlotMarker} from '../utils/types/Slots'
 import {asSlot} from '../utils/as-slot'
+import {useMergedRefs} from '../hooks'
+import {useDevOnlyEffect} from '../internal/hooks/useDevOnlyEffect'
+import {warning} from '../utils/warning'
 
 type HeadingLevels = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
 
@@ -156,7 +159,6 @@ const ItemComponent = fixedForwardRef(
     ref: React.ForwardedRef<unknown>,
   ) => {
     const {depth} = React.useContext(SubNavContext)
-    const hasLinkTarget = Boolean(props.href || (Component && Component !== 'a'))
 
     // Extract SubNav from children; useSlots also returns `rest` with TrailingAction filtered out.
     const [slots, childrenWithoutSubNavOrTrailingAction] = useSlots(children, {
@@ -169,27 +171,19 @@ const ItemComponent = fixedForwardRef(
       // eslint-disable-next-line no-console
       console.error('NavList.Item must have a NavList.SubNav to use defaultOpen.')
 
-    if (subNavToggleLabel && !hasLinkTarget)
-      // eslint-disable-next-line no-console
-      console.error('NavList.Item must have an href or custom link component to use subNavToggleLabel.')
-
     // Render ItemWithSubNav if SubNav is present
     if (subNav && isValidElement(subNav)) {
       return (
-        <ItemWithSubNav
+        <ItemWithSubNav<As>
           subNav={subNav}
           depth={depth}
           defaultOpen={defaultOpen}
-          subNavToggleLabel={hasLinkTarget ? subNavToggleLabel : undefined}
+          subNavToggleLabel={subNavToggleLabel}
           tooltipText={tooltipText}
           ariaCurrent={ariaCurrent}
-          style={{'--subitem-depth': depth} as React.CSSProperties}
-          linkProps={{
-            ref,
-            as: Component,
-            'aria-current': ariaCurrent,
-            ...props,
-          }}
+          as={Component}
+          forwardedRef={ref}
+          linkProps={props}
         >
           {childrenWithoutSubNavOrTrailingAction}
         </ItemWithSubNav>
@@ -223,7 +217,16 @@ const Item = Object.assign(ItemComponent, {displayName: 'NavList.Item'})
 // ----------------------------------------------------------------------------
 // ItemWithSubNav (internal)
 
-type ItemWithSubNavProps = {
+type ItemWithSubNavLinkProps<As extends React.ElementType> = Omit<
+  NavListItemProps<As>,
+  'aria-current' | 'as' | 'children' | 'defaultOpen' | 'subNavToggleLabel' | 'tooltipText'
+> & {
+  className?: string
+  id?: string
+  style?: React.CSSProperties
+}
+
+type ItemWithSubNavProps<As extends React.ElementType> = {
   children: React.ReactNode
   subNav: React.ReactNode
   depth: number
@@ -231,14 +234,21 @@ type ItemWithSubNavProps = {
   subNavToggleLabel?: string
   tooltipText?: string
   ariaCurrent?: NavListItemProps['aria-current']
-  style: React.CSSProperties
-  linkProps: Record<string, unknown>
+  as?: As
+  forwardedRef: React.ForwardedRef<unknown>
+  linkProps: ItemWithSubNavLinkProps<As>
 }
 
-const ItemWithSubNavContext = React.createContext<{buttonId: string; subNavId: string; isOpen: boolean}>({
+const ItemWithSubNavContext = React.createContext<{
+  buttonId: string
+  subNavId: string
+  isOpen: boolean
+  linked: boolean
+}>({
   buttonId: '',
   subNavId: '',
   isOpen: false,
+  linked: false,
 })
 
 function hasCurrentNavItem(node: React.ReactNode): boolean {
@@ -263,19 +273,23 @@ function hasCurrentNavItem(node: React.ReactNode): boolean {
   return React.Children.toArray(node.props.children).some(hasCurrentNavItem)
 }
 
-function ItemWithSubNav({
+function ItemWithSubNav<As extends React.ElementType = 'a'>({
   children,
   subNav,
-  depth: _depth,
+  depth,
   defaultOpen,
   subNavToggleLabel,
   tooltipText,
   ariaCurrent,
-  style,
+  as: Component,
+  forwardedRef,
   linkProps,
-}: ItemWithSubNavProps) {
-  const buttonId = useId()
+}: ItemWithSubNavProps<As>) {
+  const {className, id, style, ...restLinkProps} = linkProps
+  const buttonId = useId(id)
   const subNavId = useId()
+  const linkRef = React.useRef<HTMLElement>(null)
+  const mergedLinkRef = useMergedRefs(forwardedRef, linkRef)
 
   // We have to use recursion to check if the current nav item is part of the subnav before initial render
   // which is why we can't use the querySelector on the ref as it will cause the parent item to blink during first render.
@@ -307,16 +321,30 @@ function ItemWithSubNav({
   )
 
   const toggleSubNav = () => setIsOpen(open => !open)
+  const linked = Boolean(subNavToggleLabel)
+  const InternalLinkItem: React.ElementType = ActionList.LinkItem
+
+  useDevOnlyEffect(() => {
+    if (!linked) return
+
+    warning(
+      !linkRef.current || !(linkRef.current instanceof HTMLAnchorElement) || !linkRef.current.hasAttribute('href'),
+      'NavList.Item with subNavToggleLabel must render an anchor with an href.',
+    )
+  }, [linked])
 
   return (
-    <ItemWithSubNavContext.Provider value={{buttonId, subNavId, isOpen}}>
+    <ItemWithSubNavContext.Provider value={{buttonId, subNavId, isOpen, linked}}>
       {subNavToggleLabel ? (
-        <ActionList.LinkItem
-          {...linkProps}
+        <InternalLinkItem
+          {...restLinkProps}
+          ref={mergedLinkRef}
+          as={Component}
+          aria-current={ariaCurrent}
           id={buttonId}
           active={(Boolean(ariaCurrent) && ariaCurrent !== 'false') || (!isOpen && containsCurrentItem)}
-          className={clsx(linkProps.className as string | undefined, navListClasses.LinkedSubNavItem)}
-          style={style}
+          className={clsx(className, navListClasses.LinkedSubNavItem)}
+          style={{'--subitem-depth': depth, ...style} as React.CSSProperties}
           data-component="NavList.Item"
           _PrivateTooltipText={tooltipText}
         >
@@ -325,12 +353,12 @@ function ItemWithSubNav({
             aria-controls={subNavId}
             aria-expanded={isOpen}
             className={navListClasses.SubNavToggle}
-            icon={ChevronDownIcon}
+            icon={isOpen ? ChevronUpIcon : ChevronDownIcon}
             label={subNavToggleLabel}
             onClick={toggleSubNav}
           />
           {subItem}
-        </ActionList.LinkItem>
+        </InternalLinkItem>
       ) : (
         <ActionList.Item
           id={buttonId}
@@ -338,7 +366,7 @@ function ItemWithSubNav({
           aria-controls={subNavId}
           active={!isOpen && containsCurrentItem}
           onSelect={toggleSubNav}
-          style={style}
+          style={{'--subitem-depth': depth} as React.CSSProperties}
           data-component="NavList.Item"
           _PrivateTooltipText={tooltipText}
         >
@@ -364,7 +392,7 @@ const SubNavContext = React.createContext<{depth: number}>({depth: 0})
 
 // NOTE: SubNav must be a direct child of an Item
 const SubNav = React.forwardRef<HTMLUListElement, NavListSubNavProps>(({children}, forwardedRef) => {
-  const {buttonId, subNavId, isOpen} = React.useContext(ItemWithSubNavContext)
+  const {buttonId, subNavId, isOpen, linked} = React.useContext(ItemWithSubNavContext)
   const {depth} = React.useContext(SubNavContext)
   if (!buttonId || !subNavId) {
     // eslint-disable-next-line no-console
@@ -381,7 +409,7 @@ const SubNav = React.forwardRef<HTMLUListElement, NavListSubNavProps>(({children
   return (
     <SubNavContext.Provider value={{depth: depth + 1}}>
       <ul
-        className={classes.SubGroup}
+        className={clsx(classes.SubGroup, linked && navListClasses.LinkedSubNav)}
         id={subNavId}
         aria-labelledby={buttonId}
         hidden={!isOpen}

From b8b069f960863d1d9bf6ecbe0a63945d74904d9a Mon Sep 17 00:00:00 2001
From: Matt Obee <mattobee@github.com>
Date: Thu, 3 Sep 2026 14:23:49 +0100
Subject: [PATCH 3/6] Fix linked sub-nav tooltip validation

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 6f4333c6-7280-4a91-b0a0-eefc06ff8b70
---
 packages/react/src/NavList/NavList.test.tsx | 28 ++++++++++++++++++++-
 packages/react/src/NavList/NavList.tsx      |  8 +++---
 2 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/packages/react/src/NavList/NavList.test.tsx b/packages/react/src/NavList/NavList.test.tsx
index bd218e551b2..4f92002fa5b 100644
--- a/packages/react/src/NavList/NavList.test.tsx
+++ b/packages/react/src/NavList/NavList.test.tsx
@@ -272,6 +272,7 @@ describe('NavList.Item with NavList.SubNav', () => {
   })
 
   it('supports a link with a separate SubNav toggle', () => {
+    const onClick = vi.fn((event: React.MouseEvent) => event.preventDefault())
     const {getByRole, queryByRole} = render(
       <NavList>
         <NavList.Item
@@ -281,7 +282,7 @@ describe('NavList.Item with NavList.SubNav', () => {
           className="custom-class"
           style={{color: 'red'}}
           subNavToggleLabel="Toggle overview pages"
-          onClick={event => event.preventDefault()}
+          onClick={onClick}
         >
           Overview
           <NavList.SubNav>
@@ -302,13 +303,38 @@ describe('NavList.Item with NavList.SubNav', () => {
     expect(queryByRole('list', {name: 'Overview'})).toBeNull()
 
     fireEvent.click(link)
+    expect(onClick).toHaveBeenCalledOnce()
     expect(toggle).toHaveAttribute('aria-expanded', 'false')
 
+    onClick.mockClear()
     fireEvent.click(toggle)
+    expect(onClick).not.toHaveBeenCalled()
     expect(toggle).toHaveAttribute('aria-expanded', 'true')
     expect(getByRole('list', {name: 'Overview'})).toBeVisible()
   })
 
+  it('supports tooltipText on a linked SubNav parent', () => {
+    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => null)
+
+    const {getByRole} = render(
+      <NavList>
+        <NavList.Item href="/overview" subNavToggleLabel="Toggle overview pages" tooltipText="Go to overview">
+          Overview
+          <NavList.SubNav>
+            <NavList.Item href="/overview/review-requested">Review requested</NavList.Item>
+          </NavList.SubNav>
+        </NavList.Item>
+      </NavList>,
+    )
+
+    expect(getByRole('link', {name: 'Overview'})).toHaveAttribute('href', '/overview')
+    expect(consoleSpy).not.toHaveBeenCalledWith(
+      'Warning:',
+      'NavList.Item with subNavToggleLabel must render an anchor with an href.',
+    )
+    consoleSpy.mockRestore()
+  })
+
   it('forwards custom link props when using a separate SubNav toggle', () => {
     const {getByRole} = render(
       <NavList>
diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index 2620b46bd15..cb9ef1ca3b0 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -327,10 +327,10 @@ function ItemWithSubNav<As extends React.ElementType = 'a'>({
   useDevOnlyEffect(() => {
     if (!linked) return
 
-    warning(
-      !linkRef.current || !(linkRef.current instanceof HTMLAnchorElement) || !linkRef.current.hasAttribute('href'),
-      'NavList.Item with subNavToggleLabel must render an anchor with an href.',
-    )
+    const link = linkRef.current
+    const anchor = link instanceof HTMLAnchorElement ? link : link?.querySelector('a[href]')
+
+    warning(!anchor, 'NavList.Item with subNavToggleLabel must render an anchor with an href.')
   }, [linked])
 
   return (

From ae0e91dfcdb3f292e02e546ad40fa8965fc1fb88 Mon Sep 17 00:00:00 2001
From: Matt Obee <mattobee@github.com>
Date: Thu, 3 Sep 2026 14:45:45 +0100
Subject: [PATCH 4/6] Align sub-nav trailing action styling

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 6f4333c6-7280-4a91-b0a0-eefc06ff8b70
---
 .../src/ActionList/ActionList.module.css      |  20 +++-
 packages/react/src/ActionList/Item.tsx        | 108 +++++++++---------
 packages/react/src/NavList/NavList.module.css |  17 ---
 packages/react/src/NavList/NavList.tsx        |  17 +--
 4 files changed, 79 insertions(+), 83 deletions(-)

diff --git a/packages/react/src/ActionList/ActionList.module.css b/packages/react/src/ActionList/ActionList.module.css
index aa7d807f673..b3351b6972b 100644
--- a/packages/react/src/ActionList/ActionList.module.css
+++ b/packages/react/src/ActionList/ActionList.module.css
@@ -115,7 +115,7 @@
   border-radius: var(--borderRadius-medium);
 
   /* apply flex if trailing action exists as an immediate child */
-  &[data-has-trailing-action] {
+  &[data-has-trailing-action]:not([data-has-subitem='true']) {
     display: flex;
     flex-wrap: nowrap;
   }
@@ -497,6 +497,24 @@
 
 /* button or a tag */
 
+.ActionListItemRow {
+  display: flex;
+  border-radius: var(--borderRadius-medium);
+
+  @media (hover: hover) {
+    &:hover {
+      background-color: var(--control-transparent-bgColor-hover);
+      outline: solid var(--borderWidth-thin) transparent;
+      outline-offset: calc(-1 * var(--borderWidth-thin));
+      box-shadow: var(--boxShadow-thin) var(--control-transparent-borderColor-active);
+    }
+  }
+
+  &:active {
+    background-color: var(--control-transparent-bgColor-active);
+  }
+}
+
 /* [ [spacer] [leadingAction] [leadingVisual] [content] ] */
 .ActionListContent {
   --subitem-depth: 0px;
diff --git a/packages/react/src/ActionList/Item.tsx b/packages/react/src/ActionList/Item.tsx
index 1606952e3e1..2957b3ff6f1 100644
--- a/packages/react/src/ActionList/Item.tsx
+++ b/packages/react/src/ActionList/Item.tsx
@@ -334,67 +334,69 @@ const UnwrappedItem = <As extends React.ElementType = 'li'>(
         data-trailing-action-loading={trailingActionRendered && slots.trailingAction?.props.loading ? true : undefined}
         className={clsx(classes.ActionListItem, className)}
       >
-        <ConditionalTooltip ref={forwardedRef} text={_PrivateTooltipText ?? truncatedText} enabled={buttonSemantics}>
-          <ItemWrapper
-            {...wrapperProps}
-            className={classes.ActionListContent}
-            data-size={size}
-            // @ts-ignore: ItemWrapper is polymorphic and the ref type depends on the rendered element ('button' or 'li')
-            ref={forwardedRef}
-          >
-            {/* Reset TooltipContext so that child components don't detect
-                the ConditionalTooltip and suppress their own internal tooltips. */}
-            <TooltipContext.Provider value={{}}>
-              <span className={classes.Spacer} />
-              <Selection selected={selected} className={classes.LeadingAction} />
-              <VisualOrIndicator
-                inactiveText={showInactiveIndicator ? inactiveText : undefined}
-                itemHasLeadingVisual={Boolean(slots.leadingVisual)}
-                labelId={labelId}
-                loading={loading}
-                position="leading"
-              >
-                {slots.leadingVisual}
-              </VisualOrIndicator>
-              {/* TODO: next-major: change to data-component="ActionList.Item.DividerContainer" next major version */}
-              <span className={classes.ActionListSubContent} data-component="ActionList.Item--DividerContainer">
-                <ConditionalWrapper
-                  if={!!slots.description}
-                  className={classes.ItemDescriptionWrap}
-                  data-description-variant={descriptionVariant}
-                >
-                  <span id={labelId} className={classes.ItemLabel} data-component="ActionList.Item.Label">
-                    {childrenWithoutSlots}
-                    {/* Loading message needs to be in here so it is read with the label */}
-                    {/* If the item is inactive, we do not simultaneously announce that it is loading */}
-                    {loading === true && !inactive && <VisuallyHidden>Loading</VisuallyHidden>}
-                  </span>
-                  {slots.description}
-                </ConditionalWrapper>
+        <ConditionalWrapper if={Boolean(slots.subItem && trailingActionRendered)} className={classes.ActionListItemRow}>
+          <ConditionalTooltip ref={forwardedRef} text={_PrivateTooltipText ?? truncatedText} enabled={buttonSemantics}>
+            <ItemWrapper
+              {...wrapperProps}
+              className={classes.ActionListContent}
+              data-size={size}
+              // @ts-ignore: ItemWrapper is polymorphic and the ref type depends on the rendered element ('button' or 'li')
+              ref={forwardedRef}
+            >
+              {/* Reset TooltipContext so that child components don't detect
+                  the ConditionalTooltip and suppress their own internal tooltips. */}
+              <TooltipContext.Provider value={{}}>
+                <span className={classes.Spacer} />
+                <Selection selected={selected} className={classes.LeadingAction} />
                 <VisualOrIndicator
                   inactiveText={showInactiveIndicator ? inactiveText : undefined}
                   itemHasLeadingVisual={Boolean(slots.leadingVisual)}
                   labelId={labelId}
                   loading={loading}
-                  position="trailing"
+                  position="leading"
                 >
-                  {trailingVisual}
+                  {slots.leadingVisual}
                 </VisualOrIndicator>
-
-                {
-                  // If the item is inactive, but it's not in an overlay (e.g. ActionMenu, SelectPanel),
-                  // render the inactive warning message directly in the item.
-                  !showInactiveIndicator && inactiveText ? (
-                    <span className={classes.InactiveWarning} id={inactiveWarningId}>
-                      {inactiveText}
+                {/* TODO: next-major: change to data-component="ActionList.Item.DividerContainer" next major version */}
+                <span className={classes.ActionListSubContent} data-component="ActionList.Item--DividerContainer">
+                  <ConditionalWrapper
+                    if={!!slots.description}
+                    className={classes.ItemDescriptionWrap}
+                    data-description-variant={descriptionVariant}
+                  >
+                    <span id={labelId} className={classes.ItemLabel} data-component="ActionList.Item.Label">
+                      {childrenWithoutSlots}
+                      {/* Loading message needs to be in here so it is read with the label */}
+                      {/* If the item is inactive, we do not simultaneously announce that it is loading */}
+                      {loading === true && !inactive && <VisuallyHidden>Loading</VisuallyHidden>}
                     </span>
-                  ) : null
-                }
-              </span>
-            </TooltipContext.Provider>
-          </ItemWrapper>
-        </ConditionalTooltip>
-        {!inactive && !loading && !menuContext && Boolean(slots.trailingAction) && slots.trailingAction}
+                    {slots.description}
+                  </ConditionalWrapper>
+                  <VisualOrIndicator
+                    inactiveText={showInactiveIndicator ? inactiveText : undefined}
+                    itemHasLeadingVisual={Boolean(slots.leadingVisual)}
+                    labelId={labelId}
+                    loading={loading}
+                    position="trailing"
+                  >
+                    {trailingVisual}
+                  </VisualOrIndicator>
+
+                  {
+                    // If the item is inactive, but it's not in an overlay (e.g. ActionMenu, SelectPanel),
+                    // render the inactive warning message directly in the item.
+                    !showInactiveIndicator && inactiveText ? (
+                      <span className={classes.InactiveWarning} id={inactiveWarningId}>
+                        {inactiveText}
+                      </span>
+                    ) : null
+                  }
+                </span>
+              </TooltipContext.Provider>
+            </ItemWrapper>
+          </ConditionalTooltip>
+          {!inactive && !loading && !menuContext && Boolean(slots.trailingAction) && slots.trailingAction}
+        </ConditionalWrapper>
         {slots.subItem}
       </li>
     </ItemContext.Provider>
diff --git a/packages/react/src/NavList/NavList.module.css b/packages/react/src/NavList/NavList.module.css
index babef5120f2..93dbb6674eb 100644
--- a/packages/react/src/NavList/NavList.module.css
+++ b/packages/react/src/NavList/NavList.module.css
@@ -12,20 +12,3 @@
 .GroupHeading > a:hover {
   text-decoration: underline;
 }
-
-/* Match ActionList's attribute-selector specificity without depending on its DOM attributes. */
-.LinkedSubNavItem.LinkedSubNavItem {
-  display: grid;
-  grid-template-columns: minmax(0, 1fr) min-content;
-}
-
-.SubNavToggle.SubNavToggle {
-  grid-area: auto;
-  grid-row: 1;
-  grid-column: 2;
-}
-
-.LinkedSubNav.LinkedSubNav {
-  grid-row: 2;
-  grid-column: 1 / -1;
-}
diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index cb9ef1ca3b0..fcd7b0afdaf 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -239,16 +239,10 @@ type ItemWithSubNavProps<As extends React.ElementType> = {
   linkProps: ItemWithSubNavLinkProps<As>
 }
 
-const ItemWithSubNavContext = React.createContext<{
-  buttonId: string
-  subNavId: string
-  isOpen: boolean
-  linked: boolean
-}>({
+const ItemWithSubNavContext = React.createContext<{buttonId: string; subNavId: string; isOpen: boolean}>({
   buttonId: '',
   subNavId: '',
   isOpen: false,
-  linked: false,
 })
 
 function hasCurrentNavItem(node: React.ReactNode): boolean {
@@ -334,7 +328,7 @@ function ItemWithSubNav<As extends React.ElementType = 'a'>({
   }, [linked])
 
   return (
-    <ItemWithSubNavContext.Provider value={{buttonId, subNavId, isOpen, linked}}>
+    <ItemWithSubNavContext.Provider value={{buttonId, subNavId, isOpen}}>
       {subNavToggleLabel ? (
         <InternalLinkItem
           {...restLinkProps}
@@ -343,7 +337,7 @@ function ItemWithSubNav<As extends React.ElementType = 'a'>({
           aria-current={ariaCurrent}
           id={buttonId}
           active={(Boolean(ariaCurrent) && ariaCurrent !== 'false') || (!isOpen && containsCurrentItem)}
-          className={clsx(className, navListClasses.LinkedSubNavItem)}
+          className={className}
           style={{'--subitem-depth': depth, ...style} as React.CSSProperties}
           data-component="NavList.Item"
           _PrivateTooltipText={tooltipText}
@@ -352,7 +346,6 @@ function ItemWithSubNav<As extends React.ElementType = 'a'>({
           <ActionList.TrailingAction
             aria-controls={subNavId}
             aria-expanded={isOpen}
-            className={navListClasses.SubNavToggle}
             icon={isOpen ? ChevronUpIcon : ChevronDownIcon}
             label={subNavToggleLabel}
             onClick={toggleSubNav}
@@ -392,7 +385,7 @@ const SubNavContext = React.createContext<{depth: number}>({depth: 0})
 
 // NOTE: SubNav must be a direct child of an Item
 const SubNav = React.forwardRef<HTMLUListElement, NavListSubNavProps>(({children}, forwardedRef) => {
-  const {buttonId, subNavId, isOpen, linked} = React.useContext(ItemWithSubNavContext)
+  const {buttonId, subNavId, isOpen} = React.useContext(ItemWithSubNavContext)
   const {depth} = React.useContext(SubNavContext)
   if (!buttonId || !subNavId) {
     // eslint-disable-next-line no-console
@@ -409,7 +402,7 @@ const SubNav = React.forwardRef<HTMLUListElement, NavListSubNavProps>(({children
   return (
     <SubNavContext.Provider value={{depth: depth + 1}}>
       <ul
-        className={clsx(classes.SubGroup, linked && navListClasses.LinkedSubNav)}
+        className={classes.SubGroup}
         id={subNavId}
         aria-labelledby={buttonId}
         hidden={!isOpen}

From eaefe818f5211a3d4b96c2824449529e2d4ff045 Mon Sep 17 00:00:00 2001
From: Matt Obee <mattobee@github.com>
Date: Thu, 3 Sep 2026 14:46:36 +0100
Subject: [PATCH 5/6] Remove duplicate linked-item validation

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 6f4333c6-7280-4a91-b0a0-eefc06ff8b70
---
 packages/react/src/NavList/NavList.test.tsx | 68 ---------------------
 packages/react/src/NavList/NavList.tsx      | 17 +-----
 2 files changed, 1 insertion(+), 84 deletions(-)

diff --git a/packages/react/src/NavList/NavList.test.tsx b/packages/react/src/NavList/NavList.test.tsx
index 4f92002fa5b..359b5272fc8 100644
--- a/packages/react/src/NavList/NavList.test.tsx
+++ b/packages/react/src/NavList/NavList.test.tsx
@@ -313,28 +313,6 @@ describe('NavList.Item with NavList.SubNav', () => {
     expect(getByRole('list', {name: 'Overview'})).toBeVisible()
   })
 
-  it('supports tooltipText on a linked SubNav parent', () => {
-    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => null)
-
-    const {getByRole} = render(
-      <NavList>
-        <NavList.Item href="/overview" subNavToggleLabel="Toggle overview pages" tooltipText="Go to overview">
-          Overview
-          <NavList.SubNav>
-            <NavList.Item href="/overview/review-requested">Review requested</NavList.Item>
-          </NavList.SubNav>
-        </NavList.Item>
-      </NavList>,
-    )
-
-    expect(getByRole('link', {name: 'Overview'})).toHaveAttribute('href', '/overview')
-    expect(consoleSpy).not.toHaveBeenCalledWith(
-      'Warning:',
-      'NavList.Item with subNavToggleLabel must render an anchor with an href.',
-    )
-    consoleSpy.mockRestore()
-  })
-
   it('forwards custom link props when using a separate SubNav toggle', () => {
     const {getByRole} = render(
       <NavList>
@@ -350,52 +328,6 @@ describe('NavList.Item with NavList.SubNav', () => {
     expect(getByRole('link', {name: 'Overview'})).toHaveAttribute('href', '/overview')
   })
 
-  it('warns when a linked SubNav parent does not render an anchor', () => {
-    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => null)
-
-    const {getByRole} = render(
-      <NavList>
-        <NavList.Item as="button" subNavToggleLabel="Toggle overview pages">
-          Overview
-          <NavList.SubNav>
-            <NavList.Item href="/overview/review-requested">Review requested</NavList.Item>
-          </NavList.SubNav>
-        </NavList.Item>
-      </NavList>,
-    )
-
-    expect(getByRole('button', {name: 'Overview'})).toBeInTheDocument()
-    expect(consoleSpy).toHaveBeenCalledWith(
-      'Warning:',
-      'NavList.Item with subNavToggleLabel must render an anchor with an href.',
-    )
-    consoleSpy.mockRestore()
-  })
-
-  it('warns when a custom linked SubNav parent does not forward its ref', () => {
-    const CustomLink = React.forwardRef<HTMLAnchorElement, {children?: React.ReactNode; href?: string}>(
-      ({children}, _ref) => <div>{children}</div>,
-    )
-    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => null)
-
-    render(
-      <NavList>
-        <NavList.Item as={CustomLink} href="/overview" subNavToggleLabel="Toggle overview pages">
-          Overview
-          <NavList.SubNav>
-            <NavList.Item href="/overview/review-requested">Review requested</NavList.Item>
-          </NavList.SubNav>
-        </NavList.Item>
-      </NavList>,
-    )
-
-    expect(consoleSpy).toHaveBeenCalledWith(
-      'Warning:',
-      'NavList.Item with subNavToggleLabel must render an anchor with an href.',
-    )
-    consoleSpy.mockRestore()
-  })
-
   it('prevents more than 4 levels of nested SubNavs', () => {
     const consoleSpy = vi
       .spyOn(console, 'error')
diff --git a/packages/react/src/NavList/NavList.tsx b/packages/react/src/NavList/NavList.tsx
index fcd7b0afdaf..ed23efe1bf6 100644
--- a/packages/react/src/NavList/NavList.tsx
+++ b/packages/react/src/NavList/NavList.tsx
@@ -23,9 +23,6 @@ import HeadingComponent from '../Heading'
 import visuallyHiddenClasses from '../_VisuallyHidden.module.css'
 import type {FCWithSlotMarker} from '../utils/types/Slots'
 import {asSlot} from '../utils/as-slot'
-import {useMergedRefs} from '../hooks'
-import {useDevOnlyEffect} from '../internal/hooks/useDevOnlyEffect'
-import {warning} from '../utils/warning'
 
 type HeadingLevels = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
 
@@ -282,8 +279,6 @@ function ItemWithSubNav<As extends React.ElementType = 'a'>({
   const {className, id, style, ...restLinkProps} = linkProps
   const buttonId = useId(id)
   const subNavId = useId()
-  const linkRef = React.useRef<HTMLElement>(null)
-  const mergedLinkRef = useMergedRefs(forwardedRef, linkRef)
 
   // We have to use recursion to check if the current nav item is part of the subnav before initial render
   // which is why we can't use the querySelector on the ref as it will cause the parent item to blink during first render.
@@ -315,24 +310,14 @@ function ItemWithSubNav<As extends React.ElementType = 'a'>({
   )
 
   const toggleSubNav = () => setIsOpen(open => !open)
-  const linked = Boolean(subNavToggleLabel)
   const InternalLinkItem: React.ElementType = ActionList.LinkItem
 
-  useDevOnlyEffect(() => {
-    if (!linked) return
-
-    const link = linkRef.current
-    const anchor = link instanceof HTMLAnchorElement ? link : link?.querySelector('a[href]')
-
-    warning(!anchor, 'NavList.Item with subNavToggleLabel must render an anchor with an href.')
-  }, [linked])
-
   return (
     <ItemWithSubNavContext.Provider value={{buttonId, subNavId, isOpen}}>
       {subNavToggleLabel ? (
         <InternalLinkItem
           {...restLinkProps}
-          ref={mergedLinkRef}
+          ref={forwardedRef}
           as={Component}
           aria-current={ariaCurrent}
           id={buttonId}

From 2945d6daf6834d1b5327afbada085c7309ed3de2 Mon Sep 17 00:00:00 2001
From: Matt Obee <mattobee@github.com>
Date: Thu, 3 Sep 2026 14:49:57 +0100
Subject: [PATCH 6/6] Rename linked sub-nav changeset

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 6f4333c6-7280-4a91-b0a0-eefc06ff8b70
---
 .changeset/{lazy-linked-subnav.md => navlist-linked-subnav.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename .changeset/{lazy-linked-subnav.md => navlist-linked-subnav.md} (100%)

diff --git a/.changeset/lazy-linked-subnav.md b/.changeset/navlist-linked-subnav.md
similarity index 100%
rename from .changeset/lazy-linked-subnav.md
rename to .changeset/navlist-linked-subnav.md