From 2edbc3bce6140eb7a74ab9dcc98572f1822d735a Mon Sep 17 00:00:00 2001
From: Matyas Forian-Szabo <matyas.szabo@instructure.com>
Date: Wed, 28 Jan 2026 13:54:42 +0100
Subject: [PATCH] feat(ui-top-nav-bar): allow to set aria-label on TopNavBar's
 overflow menu button

The new prop renderHiddenItemsMenuTriggerAriaLabel sets the aria-label on the desktop TopNavBar's
overflow menu (e.g. 7 More). This is needed because often the the button's text is not descriptive
enough for screenreader users.

INSTUI-4898
---
 .../ui-top-nav-bar/src/TopNavBar/README.md    | 24 +++++++++++++++++++
 .../__tests__/TopNavBarMenuItems.test.tsx     | 23 ++++++++++++++++++
 .../TopNavBar/TopNavBarMenuItems/index.tsx    | 11 ++++++++-
 .../src/TopNavBar/TopNavBarMenuItems/props.ts | 10 ++++++++
 4 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/packages/ui-top-nav-bar/src/TopNavBar/README.md b/packages/ui-top-nav-bar/src/TopNavBar/README.md
index 5640525339..9b293a9481 100644
--- a/packages/ui-top-nav-bar/src/TopNavBar/README.md
+++ b/packages/ui-top-nav-bar/src/TopNavBar/README.md
@@ -633,6 +633,9 @@ class PlaygroundExample extends React.Component {
                   renderHiddenItemsMenuTriggerLabel={(
                     hiddenChildrenCount
                   ) => `${hiddenChildrenCount} More`}
+                  renderHiddenItemsMenuTriggerAriaLabel={(
+                    hiddenChildrenCount
+                  ) => `${hiddenChildrenCount} more menu items`}
                 >
                   {navItems.map(item => (
                     <TopNavBar.Item
@@ -1223,6 +1226,9 @@ type: example
               renderHiddenItemsMenuTriggerLabel={(
                 hiddenChildrenCount
               ) => `${hiddenChildrenCount} More`}
+              renderHiddenItemsMenuTriggerAriaLabel={(
+                hiddenChildrenCount
+              ) => `${hiddenChildrenCount} more menu items`}
             >
               {Array.from(Array(4)).map((_item, idx) => (
                 <TopNavBar.Item
@@ -1271,6 +1277,9 @@ type: example
               renderHiddenItemsMenuTriggerLabel={(
                 hiddenChildrenCount
               ) => `${hiddenChildrenCount} More`}
+              renderHiddenItemsMenuTriggerAriaLabel={(
+                hiddenChildrenCount
+              ) => `${hiddenChildrenCount} more menu items`}
             >
               {Array.from(Array(14)).map((_item, idx) => (
                 <TopNavBar.Item
@@ -1694,6 +1703,9 @@ class LayoutExample extends React.Component {
                         renderHiddenItemsMenuTriggerLabel={(
                           hiddenChildrenCount
                         ) => `${hiddenChildrenCount} More`}
+                        renderHiddenItemsMenuTriggerAriaLabel={(
+                          hiddenChildrenCount
+                        ) => `${hiddenChildrenCount} more menu items`}
                       >
                         <TopNavBar.Item
                           id="OverviewPage"
@@ -1981,6 +1993,9 @@ type: example
               renderHiddenItemsMenuTriggerLabel={(
                 hiddenChildrenCount
               ) => `${hiddenChildrenCount} More`}
+             renderHiddenItemsMenuTriggerAriaLabel={(
+               hiddenChildrenCount
+             ) => `${hiddenChildrenCount} more menu items`}
             >
               <TopNavBar.Item
                 id="itemSubmenuExample"
@@ -2018,6 +2033,9 @@ type: example
               renderHiddenItemsMenuTriggerLabel={(
                 hiddenChildrenCount
               ) => `${hiddenChildrenCount} More`}
+             renderHiddenItemsMenuTriggerAriaLabel={(
+               hiddenChildrenCount
+             ) => `${hiddenChildrenCount} more menu items`}
             >
               <TopNavBar.Item
                 id="itemTooltipExample"
@@ -2164,6 +2182,9 @@ class InPlaceDialogExample extends React.Component {
                   renderHiddenItemsMenuTriggerLabel={(
                     hiddenChildrenCount
                   ) => `${hiddenChildrenCount} More`}
+                 renderHiddenItemsMenuTriggerAriaLabel={(
+                   hiddenChildrenCount
+                 ) => `${hiddenChildrenCount} more menu items`}
                 >
                   <TopNavBar.Item
                     id="Search2"
@@ -2248,6 +2269,9 @@ type: example
                 renderHiddenItemsMenuTriggerLabel={(
                   hiddenChildrenCount
                 ) => `${hiddenChildrenCount} More`}
+                renderHiddenItemsMenuTriggerAriaLabel={(
+                  hiddenChildrenCount
+                ) => `${hiddenChildrenCount} more menu items`}
               >
                 <TopNavBar.Item
                   id="OverviewPage"
diff --git a/packages/ui-top-nav-bar/src/TopNavBar/TopNavBarMenuItems/__tests__/TopNavBarMenuItems.test.tsx b/packages/ui-top-nav-bar/src/TopNavBar/TopNavBarMenuItems/__tests__/TopNavBarMenuItems.test.tsx
index 19bf843819..f0823ff25e 100644
--- a/packages/ui-top-nav-bar/src/TopNavBar/TopNavBarMenuItems/__tests__/TopNavBarMenuItems.test.tsx
+++ b/packages/ui-top-nav-bar/src/TopNavBar/TopNavBarMenuItems/__tests__/TopNavBarMenuItems.test.tsx
@@ -253,6 +253,29 @@ describe('<TopNavBarMenuItems />', () => {
     })
   })
 
+  describe('renderHiddenItemsMenuTriggerAriaLabel prop', () => {
+    it('should set the aria-label for the trigger item of the hidden list items menu', () => {
+      const { container } = render(
+        <div style={{ width: '400px' }}>
+          {getMenuItems({
+            menuItemsCount: 6,
+            menuItemsProps: {
+              renderHiddenItemsMenuTriggerLabel: (hiddenChildrenCount) =>
+                `${hiddenChildrenCount} More`,
+              renderHiddenItemsMenuTriggerAriaLabel: (hiddenChildrenCount) =>
+                `${hiddenChildrenCount} more menu items`
+            }
+          })}
+        </div>
+      )
+      const triggerItem = container.querySelector(
+        '[id*="-hiddenMenuItemsMenuTrigger"]'
+      )
+
+      expect(triggerItem).toHaveAttribute('aria-label', '6 more menu items')
+    })
+  })
+
   describe('currentPageId prop', () => {
     it('should set the item with id as active', async () => {
       const { container } = render(
diff --git a/packages/ui-top-nav-bar/src/TopNavBar/TopNavBarMenuItems/index.tsx b/packages/ui-top-nav-bar/src/TopNavBar/TopNavBarMenuItems/index.tsx
index dcedeecc9c..f8b0d849f4 100644
--- a/packages/ui-top-nav-bar/src/TopNavBar/TopNavBarMenuItems/index.tsx
+++ b/packages/ui-top-nav-bar/src/TopNavBar/TopNavBarMenuItems/index.tsx
@@ -138,7 +138,11 @@ class TopNavBarMenuItems extends Component<
   }
 
   renderHiddenItemsMenu(hiddenItems: ItemChild[]) {
-    const { renderHiddenItemsMenuTriggerLabel, currentPageId } = this.props
+    const {
+      currentPageId,
+      renderHiddenItemsMenuTriggerLabel,
+      renderHiddenItemsMenuTriggerAriaLabel
+    } = this.props
 
     if (!hiddenItems.length) {
       return <span></span>
@@ -157,6 +161,11 @@ class TopNavBarMenuItems extends Component<
 
     return (
       <TopNavBarItem
+        aria-label={
+          renderHiddenItemsMenuTriggerAriaLabel
+            ? renderHiddenItemsMenuTriggerAriaLabel(hiddenItems.length)
+            : undefined
+        }
         id={this._hiddenMenuItemsMenuTriggerId}
         status={hasActiveChild ? 'active' : 'default'}
         renderSubmenu={
diff --git a/packages/ui-top-nav-bar/src/TopNavBar/TopNavBarMenuItems/props.ts b/packages/ui-top-nav-bar/src/TopNavBar/TopNavBarMenuItems/props.ts
index 284c102c2e..b611328179 100644
--- a/packages/ui-top-nav-bar/src/TopNavBar/TopNavBarMenuItems/props.ts
+++ b/packages/ui-top-nav-bar/src/TopNavBar/TopNavBarMenuItems/props.ts
@@ -67,6 +67,15 @@ type TopNavBarMenuItemsOwnProps = {
     hiddenChildrenCount: number
   ) => React.ReactNode
 
+  /**
+   * The screenreader label (`aria-label`) used for the overflow dropdown button.
+   * By default, screenreaders will read the button text (e.g. "4 More"), but
+   * this is usually not descriptive enough for screenreader users. One should
+   * specify a more descriptive label for the button, such as "4 more menu items".
+   */
+  renderHiddenItemsMenuTriggerAriaLabel?: (
+    hiddenChildrenCount: number
+  ) => string
   /**
    * In __desktop__ mode, 'aria-label' for the `<ul>` container.
    */
@@ -101,6 +110,7 @@ const allowedProps: AllowedPropKeys = [
   'children',
   'currentPageId',
   'renderHiddenItemsMenuTriggerLabel',
+  'renderHiddenItemsMenuTriggerAriaLabel',
   'listLabel',
   'elementRef'
 ]