UnderlineNav: Show item icons above medium by default

.changeset/underline-nav-icon-breakpoint.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+UnderlineNav: Keep item icons visible by default at the medium breakpoint and above

packages/react/src/UnderlineNav/UnderlineNav.docs.json

@@ -50,6 +50,12 @@
       "defaultValue": "false",
       "description": "Whether the navigation items are in loading state. Component waits for all the counters to finish loading to prevent multiple layout shifts."
     },
+    {
+      "name": "hideIconsBreakpoint",
+      "type": "'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'xxlarge' | null",
+      "defaultValue": "'medium'",
+      "description": "Controls the container width below which icons are hidden to save space. To keep icons visible in a narrow container, use a smaller breakpoint such as `xsmall`, or set to `null` to always show icons."
+    },
     {
       "name": "variant",
       "type": "'inset' | 'flush'",
@@ -111,4 +117,3 @@
     }
   ]
 }
-

packages/react/src/UnderlineNav/UnderlineNav.features.stories.tsx

@@ -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}

packages/react/src/UnderlineNav/UnderlineNav.test.tsx

@@ -83,6 +83,29 @@ describe('UnderlineNav', () => {
     expect(list.getElementsByTagName('svg').length).toEqual(7)
   })
 
+  it('hides icons below the medium breakpoint by default', () => {
+    render(<ResponsiveUnderlineNav />)
+    expect(screen.getByRole('navigation')).toHaveAttribute('data-hide-icons-breakpoint', 'medium')
+  })
+
+  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(

packages/react/src/UnderlineNav/UnderlineNav.tsx

@@ -32,8 +32,9 @@ 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.
+   * Controls the container width below which icons are hidden to save space. Defaults to `medium`.
+   * To keep icons visible in a narrow container, use a smaller breakpoint such as `xsmall`, or set to `null` to
+   * always show icons.
    */
   hideIconsBreakpoint?: 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'xxlarge' | null
 }
@@ -47,7 +48,7 @@ export const UnderlineNav = forwardRef(
       variant = 'inset',
       className,
       children,
-      hideIconsBreakpoint = 'xxlarge',
+      hideIconsBreakpoint = 'medium',
     }: UnderlineNavProps,
     forwardedRef,
   ) => {