primer · liuliu-dev · Aug 11, 2026 · Aug 3, 2026 · Aug 4, 2026 · Aug 4, 2026
@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+UnderlineNav: Keep item icons visible by default except below the xsmall breakpoint
diff --git a/...nderlineNav-UnderlineNav-Interactions-dark-Overflow-interaction-vrt-4-linux.png b/...nderlineNav-UnderlineNav-Interactions-dark-Overflow-interaction-vrt-4-linux.png
diff --git a/...-UnderlineNav-Interactions-dark-colorblind-Overflow-interaction-vrt-4-linux.png b/...-UnderlineNav-Interactions-dark-colorblind-Overflow-interaction-vrt-4-linux.png
diff --git a/...eNav-UnderlineNav-Interactions-dark-dimmed-Overflow-interaction-vrt-4-linux.png b/...eNav-UnderlineNav-Interactions-dark-dimmed-Overflow-interaction-vrt-4-linux.png
diff --git a/...derlineNav-Interactions-dark-high-contrast-Overflow-interaction-vrt-4-linux.png b/...derlineNav-Interactions-dark-high-contrast-Overflow-interaction-vrt-4-linux.png
diff --git a/...-UnderlineNav-Interactions-dark-tritanopia-Overflow-interaction-vrt-4-linux.png b/...-UnderlineNav-Interactions-dark-tritanopia-Overflow-interaction-vrt-4-linux.png
diff --git a/...derlineNav-UnderlineNav-Interactions-light-Overflow-interaction-vrt-4-linux.png b/...derlineNav-UnderlineNav-Interactions-light-Overflow-interaction-vrt-4-linux.png
diff --git a/...UnderlineNav-Interactions-light-colorblind-Overflow-interaction-vrt-4-linux.png b/...UnderlineNav-Interactions-light-colorblind-Overflow-interaction-vrt-4-linux.png
diff --git a/...erlineNav-Interactions-light-high-contrast-Overflow-interaction-vrt-4-linux.png b/...erlineNav-Interactions-light-high-contrast-Overflow-interaction-vrt-4-linux.png
diff --git a/...UnderlineNav-Interactions-light-tritanopia-Overflow-interaction-vrt-4-linux.png b/...UnderlineNav-Interactions-light-tritanopia-Overflow-interaction-vrt-4-linux.png
diff --git a/e2e/components/UnderlineNav.test.ts b/e2e/components/UnderlineNav.test.ts
@@ -210,8 +210,11 @@ test.describe('UnderlineNav', () => {
           await page.getByRole('button', {name: 'More items'}).click()
           expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot()
 
-          await page.getByRole('menuitem', {name: 'Settings (10)'}).click()
-          expect(await page.screenshot()).toMatchSnapshot()
+          const settingsMenuItem = page.getByRole('menuitem', {name: 'Settings (10)'})
+          await settingsMenuItem.click()
+          await settingsMenuItem.waitFor({state: 'hidden'})
+          await page.getByRole('button', {name: 'More items, including current item'}).waitFor()
+          expect(await page.screenshot({animations: 'disabled'})).toMatchSnapshot()
         })
 
         test('Hide icons when there is not enough space to display all list items @vrt', async ({page}) => {

@@ -77,7 +77,7 @@ const items: {navigation: string; icon: React.ReactElement; counter?: number | s
 export const OverflowTemplate = ({initialSelectedIndex = 1}: {initialSelectedIndex?: number}) => {
   const [selectedIndex, setSelectedIndex] = React.useState<number | null>(initialSelectedIndex)
   return (
-    <UnderlineNav aria-label="Repository">
+    <UnderlineNav aria-label="Repository" hideIconsBreakpoint="medium">
       {items.map((item, index) => (
         <UnderlineNav.Item
           key={item.navigation}

@@ -83,6 +83,29 @@ describe('UnderlineNav', () => {
     expect(list.getElementsByTagName('svg').length).toEqual(7)
   })
 
+  it('hides icons below the xsmall breakpoint by default', () => {
+    render(<ResponsiveUnderlineNav />)
+    expect(screen.getByRole('navigation')).toHaveAttribute('data-hide-icons-breakpoint', 'xsmall')
+  })
+
+  it('supports customizing when icons are hidden', () => {
+    render(
+      <UnderlineNav aria-label="Repository" hideIconsBreakpoint="medium">
+        <UnderlineNav.Item>Code</UnderlineNav.Item>
+      </UnderlineNav>,
+    )
+    expect(screen.getByRole('navigation')).toHaveAttribute('data-hide-icons-breakpoint', 'medium')
+  })
+
+  it('supports always showing icons', () => {
+    render(
+      <UnderlineNav aria-label="Repository" hideIconsBreakpoint={null}>
+        <UnderlineNav.Item>Code</UnderlineNav.Item>
+      </UnderlineNav>,
+    )
+    expect(screen.getByRole('navigation')).not.toHaveAttribute('data-hide-icons-breakpoint')
+  })
+
   it('fires onSelect on click', async () => {
     const onSelect = vi.fn()
     const {getByRole} = render(

@@ -33,7 +33,7 @@ export type UnderlineNavProps = {
   variant?: 'inset' | 'flush'
   /**
    * Customize when the icons are hidden to save space. Set to `null` to always show icons.
-   * Defaults to `xxlarge`; if you know there won't be very many tabs you might set this to a smaller value.
+   * Defaults to `xsmall`.
    */
   hideIconsBreakpoint?: 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'xxlarge' | null
 }
@@ -47,7 +47,7 @@ export const UnderlineNav = forwardRef(
       variant = 'inset',
       className,
       children,
-      hideIconsBreakpoint = 'xxlarge',
+      hideIconsBreakpoint = 'xsmall',
     }: UnderlineNavProps,
     forwardedRef,
   ) => {