UnderlineNav: Improve flickering by moving icon visibility control to a one-way CSS animation

[iansan5653]

• Resolveshttps://github.com/github/primer/issues/6806

The icons in UnderlineNav can cause flickering as they cause/un-cause the container to overflow when hidden/shown. We use JS to update state to prevent this flickering, but that doesn't run until after hydration. This means that, for certain screen sizes, the icons will flicker after SSR and before client-size hydration.

This PR moves the icon visibility logic to a one-way CSS animation on supported browsers. This way, when the scroll-driven animation is triggered, it triggers the corresponding icon-hiding animation, which persists and keeps the icons hidden for the remaining life of the component.

This improves the performance significantly by shifting the calculations into CSS in supported browsers (ie, not in Firefox). This reduces the visibility of the flickering. However, unfortunately it does not completely resolve the flickering; the browser still has to paint the tabs in order to determine the overflow and then hide the icons.

Changelog

New

Changed

• Fixed icon flickering before initial render in UnderlineNav

Removed

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Merge checklist

• Added/updated tests
• Added/updated documentation
• Added/updated previews (Storybook)
• Changes are SSR compatible
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge
• (GitHub staff only) Integration tests pass at github/github-ui (Learn more about how to run integration tests)

[changeset-bot]

🦋 Changeset detected

Latest commit: fc168b4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. If this doesn't work, you can also use the original workflow here. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

To publish a canary release for integration testing, apply the Canary Release label to this PR.

[Copilot]

Pull request overview

This PR updates UnderlineNav to avoid SSR→hydration icon flicker by removing the JS “has ever overflowed” state and attempting to move icon-hiding logic entirely into CSS via scroll-driven animations.

Changes:

• Removed hasEverOverflowed state and the data-hide-icons attribute from UnderlineNav.tsx.
• Added a new hide-icons animation in UnderlineNav.module.css, intended to run once and then keep icons hidden permanently by controlling animation play state via the existing scroll-driven overflow detection.
• Minor string literal change for the overflow menu button aria-label.

Show a summary per file

File	Description
packages/react/src/UnderlineNav/UnderlineNav.tsx	Removes JS-based icon hiding (hasEverOverflowed / data-hide-icons) to rely on CSS-only behavior.
packages/react/src/UnderlineNav/UnderlineNav.module.css	Adds a one-shot animation approach intended to hide icons without JS and prevent overflow-driven flicker loops.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 2
• Review effort level: Low

[github-actions]

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. If this doesn't work, you can also use the original workflow here. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

To publish a canary release for integration testing, apply the Canary Release label to this PR.

[primer-integration]

Integration test results from github/github-ui PR:

CI Failed
VRT Failed
Projects Passed

CI check runs linting, type checking, and unit tests. Check the workflow logs for specific failures.

VRT check ensures that when visual differences are detected, the PR cannot proceed until someone acknowledges the changes by adding the "visual difference acknowledged" label.

Need help? If you believe this failure is unrelated to your changes, please reach out to the Primer team for assistance.

[iansan5653]

Closing in favor of an alternative approach #8133