`UnderlineNav`: Fix flickering by moving icon visibility control to pure CSS by iansan5653 · Pull Request #8108 · primer/react

iansan5653 · 2026-07-02T14:57:42Z

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.

To fix this, I'm moving the visibility control to pure CSS. However, to make this work we must use CSS as a state machine; otherwise we'll just get flickering for the entire page lifecycle. So I've introduced a second animation, hide-icons, which only plays once and remains applied when paused. Then I updated the scroll-driven animation to control the hide-icons play state, rather than control the visibility directly. The result is that once the animation plays once, it will remain in that state forever - no need for any JS at all.

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 · 2026-07-02T14:57:46Z

🦋 Changeset detected

Latest commit: b3e85f5

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 · 2026-07-02T14:58:24Z

⚠️ 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

iansan5653 · 2026-07-02T15:36:18Z

+@keyframes hide-icons {
+  0% {
+    display: inline;
+  }
+
+  100% {
+    display: none;
+  }
 }


I'm like 99% sure this is incorrect. Browsers will animate the property but (obviously) not smoothly; they'll discretely step from one value to the next.

Checking https://primer-770a2beee9-13348165.drafts.github.io/storybook/?path=/story/components-underlinenav-features--with-icons I don't think the icons are hiding

This turned out to be due to not setting an initial value for the variable. Which feels like a browser bug, but it's easy to solve by initializing it.

github-actions · 2026-07-02T16:24:23Z

⚠️ 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.

iansan5653 · 2026-07-02T20:49:07Z

-      overflow: hidden;
+      flex: 1;


overflow: hidden had no effect here because there's no explicit height set on this container. And it's unnecessary since the parent already has that applied.

flex: 1 fixes a separate bug where sometimes the button wouldn't float all the way to the right. It makes the tab containers take up more space to push the overflow button further out. This prevents it from looking like it's floating in space.

iansan5653 · 2026-07-02T20:51:57Z

+  animation:
+    detect-overflow linear,
+    delay-visibility forwards 0ms 5ms;


When testing on Chrome with 20x CPU slowdown, I could see an initial paint where the icons are visible, followed by a quick update to hide them. I tried several things to resolve this, including conditionally setting the animation duration to 0 seconds and also conditionally changing the start state of the animation, but they all caused unexpected side effects.

I actually think this initial flicker may be entirely unavoidable, because the browser has to paint the tabs to determine if overflow happens in order to determine whether to hide the icons or not. So I just accepted it and decided to hide the tabs with a very short animation, which delays their initial render by an almost imperceptible 5 ms. This is just long enough to get that initial paint out of the way.

iansan5653 · 2026-07-02T20:52:46Z

+  animation-fill-mode: forwards;
+  animation-timing-function: linear;
+  animation-play-state: var(--UnderlineNav_hide-icons-play-state);
+  animation-duration: 0.1ms; /* must be greater than 0 */


Interestingly, this can't be arbitrarily small; 0.0001ms is treated as 0 in Chrome. 0.1ms seems to work very consistently though.

I did try making the duration dynamic, instead of the play state, and setting the duration to 0 to immediately resolve the animation when I want to toggle it. That didn't work though; the style didn't 'stick' if the duration was increased again.

iansan5653 · 2026-07-02T20:54:34Z

+@keyframes hide-icons {
+  0% {
+    display: inline;
+  }
+
+  100% {
+    display: none;
+  }
 }


This turned out to be due to not setting an initial value for the variable. Which feels like a browser bug, but it's easy to solve by initializing it.

primer-integration · 2026-07-02T22:09:40Z

⚠️ Integration PR Outdated

This integration PR does not have the latest commit from the primer/react PR.

Integration PR references: 56140680c341a199079ac3ad783c54566e49f5c3
Latest commit on primer/react PR: 6b360c15c21b0384f0aef3a30aedb5ce6e19fc41

Please update the integration PR to reference the latest commit from the primer/react PR before reviewing workflow results.

Move icon visibility control to full CSS with unidirectional control

a789e19

iansan5653 requested a review from a team as a code owner July 2, 2026 14:57

iansan5653 requested review from TylerJDev and Copilot July 2, 2026 14:57

Copilot started reviewing on behalf of iansan5653 July 2, 2026 14:58 View session

github-actions Bot added the integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm label Jul 2, 2026

Add changeset

302d679

joshblack approved these changes Jul 2, 2026

View reviewed changes

Copilot AI reviewed Jul 2, 2026

View reviewed changes

github-actions Bot requested a deployment to storybook-preview-8108 July 2, 2026 15:02 Abandoned

iansan5653 deployed to github-pages July 2, 2026 15:12 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to storybook-preview-8108 July 2, 2026 15:19 Inactive

Remove data-hide-icons attribute selector

6fac497

iansan5653 added the Canary Release Apply this label when you want CI to create a canary release of the current PR label Jul 2, 2026

iansan5653 had a problem deploying to github-pages July 2, 2026 15:46 — with GitHub Actions Failure

bump

a10a95c

github-actions Bot temporarily deployed to storybook-preview-8108 July 2, 2026 15:57 Inactive

iansan5653 had a problem deploying to github-pages July 2, 2026 16:06 — with GitHub Actions Failure

iansan5653 added the update snapshots 🤖 Command that updates VRT snapshots on the pull request label Jul 2, 2026

github-actions Bot temporarily deployed to storybook-preview-8108 July 2, 2026 16:16 Inactive

test(vrt): update snapshots

a1f49a5

github-actions Bot added the integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm label Jul 2, 2026

primer Bot had a problem deploying to github-pages July 2, 2026 16:33 Failure

github-actions Bot temporarily deployed to storybook-preview-8108 July 2, 2026 16:43 Inactive

iansan5653 added 2 commits July 2, 2026 20:58

Bring back JS icon hiding for Firefox

15d64eb

Revert shifting lines

b79ae2e

github-actions Bot requested a deployment to storybook-preview-8108 July 2, 2026 21:08 Abandoned

iansan5653 deployed to github-pages July 2, 2026 21:18 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to storybook-preview-8108 July 2, 2026 21:18 Inactive

iansan5653 force-pushed the fix-underlinenav-flicker branch from 366cedc to b79ae2e Compare July 2, 2026 21:31

iansan5653 commented Jul 2, 2026

View reviewed changes

iansan5653 added the update snapshots 🤖 Command that updates VRT snapshots on the pull request label Jul 2, 2026

github-actions Bot requested a deployment to storybook-preview-8108 July 2, 2026 21:35 Abandoned

Update snapshots

5614068

github-actions Bot temporarily deployed to storybook-preview-8108 July 2, 2026 21:48 Inactive

Attempt to revert snapshots

6b360c1

github-actions Bot temporarily deployed to storybook-preview-8108 July 2, 2026 22:00 Inactive

iansan5653 deployed to github-pages July 2, 2026 22:08 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to storybook-preview-8108 July 2, 2026 22:08 Inactive

llastflowers added update snapshots 🤖 Command that updates VRT snapshots on the pull request and removed update snapshots 🤖 Command that updates VRT snapshots on the pull request labels Jul 2, 2026

test(vrt): update snapshots

2c8e848

github-actions Bot removed the update snapshots 🤖 Command that updates VRT snapshots on the pull request label Jul 2, 2026

primer Bot deployed to github-pages July 2, 2026 23:03 View deployment

github-actions Bot temporarily deployed to storybook-preview-8108 July 2, 2026 23:04 Inactive

Merge branch 'main' into fix-underlinenav-flicker

c9c8c00

llastflowers had a problem deploying to github-pages July 2, 2026 23:34 — with GitHub Actions Failure

github-actions Bot temporarily deployed to storybook-preview-8108 July 2, 2026 23:34 Inactive

revert mismatched snapshots to main version

b3e85f5

llastflowers deployed to github-pages July 2, 2026 23:52 — with GitHub Actions View deployment

github-actions Bot deployed to storybook-preview-8108 July 2, 2026 23:52 View deployment

llastflowers added the update snapshots 🤖 Command that updates VRT snapshots on the pull request label Jul 2, 2026

github-actions Bot removed the update snapshots 🤖 Command that updates VRT snapshots on the pull request label Jul 3, 2026

Uh oh!

Conversation

iansan5653 commented Jul 2, 2026

Changelog

New

Changed

Removed

Rollout strategy

Testing & Reviewing

Merge checklist

Uh oh!

changeset-bot Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Jul 2, 2026

⚠️ Action required

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

Uh oh!

iansan5653 Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

jonrohan Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

iansan5653 Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 2, 2026

⚠️ Action required

Uh oh!

iansan5653 Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

iansan5653 Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

iansan5653 Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

iansan5653 Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

primer-integration Bot commented Jul 2, 2026

⚠️ Integration PR Outdated

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

changeset-bot Bot commented Jul 2, 2026 •

edited

Loading