perf(hooks): Add opt-in throttling to useResizeObserver and useOverflow by mattcosta7 · Pull Request #7335 · primer/react

mattcosta7 · 2025-12-15T14:57:19Z

Summary

Performance optimizations for useResizeObserver and useOverflow hooks to improve INP, with opt-in throttling for backwards compatibility.

Changes

useResizeObserver - Added optional throttle parameter (4th argument, defaults to false)
- When throttle=false (default): behaves exactly as before - no throttling, immediate callbacks
- When throttle=true: fires callback immediately on first observation, then throttles subsequent callbacks with rAF
useOverflow - Now uses useResizeObserver with throttle=true for internal optimization
Backwards compatible - Existing consumers get unchanged behavior by default

API

useResizeObserver(callback,target?,depsArray?,throttle? // new - defaults to false for backwards compatibility)

Expected INP Impact (when throttle=true)

Scenario	Before	After	Improvement
Worst case (rapid window resizing, many observers)	~50-100ms cumulative per resize	<16ms (1 frame)	70-85% reduction
Average case (occasional resize, few observers)	~20-40ms per resize	<16ms	40-60% reduction
Best case (single resize event)	~10-20ms	<16ms	~20% reduction

Why opt-in?

Backwards compatibility - Existing consumers get the same behavior they had before
Explicit intent - Consumers who want performance gains can opt-in consciously
Use-case flexibility - Some consumers may need every resize event (analytics, animations, cumulative calculations)

Why this matters

ResizeObserver can fire many times per frame during animations or rapid resizing:

Each callback may trigger state updates → re-renders
Without throttling, this causes jank and dropped frames
rAF batching ensures maximum 1 update per frame (60fps = 16ms budget)

The "first-immediate" pattern ensures initial render gets correct size without delay.

Part of the INP performance optimization effort. See #7312 for full context.

…useOverflow - useResizeObserver fires callback immediately on first observation, then throttles with rAF - useOverflow uses the same pattern to avoid initial flash of incorrect overflow state - Added isFirstCallback ref pattern to skip throttling on initial mount Part of #7312

changeset-bot · 2025-12-15T14:57:23Z

🦋 Changeset detected

Latest commit: b999a75

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 · 2025-12-15T14:57:49Z

👋 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. Or, apply the integration-tests: skipped manually label to skip these checks.

mattcosta7 · 2025-12-15T20:52:41Z

+return
 }
 }
+ setHasOverflow(false)


I believe this is a current bug, since things can never go to not overflow states

Copilot

Pull request overview

This PR adds performance optimizations to useResizeObserver and useOverflow hooks by implementing a "first-immediate" throttling pattern. The changes aim to reduce INP (Interaction to Next Paint) scores by batching ResizeObserver callbacks using requestAnimationFrame while ensuring the initial callback fires immediately to prevent UI flash.

Key changes:

Immediate execution on first ResizeObserver callback, then rAF throttling for subsequent callbacks
Proper cleanup of pending animation frames on component unmount
Behavioral fix in useOverflow where overflow state now correctly resets to false

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
packages/react/src/hooks/useResizeObserver.ts	Added first-immediate throttling pattern with rAF batching to reduce layout thrashing during rapid resize events
packages/react/src/hooks/useOverflow.ts	Applied same throttling pattern and fixed logic to properly reset hasOverflow to false when overflow is removed
.changeset/perf-use-resize-observer.md	Documents the performance improvements as a patch-level change

francinelucca

LGTM! some non-blocking comments

primer-integration · 2025-12-22T14:28:37Z

👋 Hi from github/github-ui! Your integration PR is ready: https://github.com/github/github-ui/pull/9375

primer-integration · 2025-12-22T14:48:10Z

🔬 github-ui Integration Test Results

Check	Status	Details
CI	✅ Passed	View run
Projects (Memex)	✅ Passed	View run
VRT	✅ Passed	View run

✨ All checks passed! Your integration PR is ready for review.

github-actionsBot added the integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm label Dec 15, 2025

mattcosta7 deployed to github-pages December 15, 2025 15:12 — with GitHub Actions View deployment

github-actionsBottemporarily deployed to storybook-preview-7335 December 15, 2025 15:12 Inactive

This was referenced Dec 15, 2025
perf(UnderlinePanels): Simplify useResizeObserver usage #7340
Closed
perf(ActionBar): Document ResizeObserver throttling #7341
Closed

mattcosta7 commented Dec 15, 2025
View reviewed changes

mattcosta7 self-assigned this Dec 15, 2025

mattcosta7 marked this pull request as ready for review December 15, 2025 20:55

Merge branch 'main' into perf/use-resize-observer
0401efc

mattcosta7 requested a review from a team as a code owner December 15, 2025 20:55

mattcosta7 requested review from Copilot and francinelucca December 15, 2025 20:55

Copilotstarted reviewing on behalf of mattcosta7 December 15, 2025 20:56 View session

CopilotAI reviewed Dec 15, 2025
View reviewed changes

Comment threadpackages/react/src/hooks/useResizeObserver.ts
Comment threadpackages/react/src/hooks/useOverflow.ts
Comment threadpackages/react/src/hooks/useResizeObserver.ts
Comment threadpackages/react/src/hooks/useOverflow.ts

mattcosta7 deployed to github-pages December 15, 2025 21:05 — with GitHub Actions View deployment

github-actionsBottemporarily deployed to storybook-preview-7335 December 15, 2025 21:05 Inactive

Merge branch 'main' into perf/use-resize-observer
f3b33a7

mattcosta7 deployed to github-pages December 16, 2025 04:54 — with GitHub Actions View deployment

github-actionsBottemporarily deployed to storybook-preview-7335 December 16, 2025 04:54 Inactive

francinelucca approved these changes Dec 16, 2025
View reviewed changes

Comment threadpackages/react/src/hooks/useOverflow.ts
Comment threadpackages/react/src/hooks/useResizeObserver.ts

mattcosta7 added 2 commits December 16, 2025 19:13

update throttling behavior
9c91b8d

Merge branch 'main' into perf/use-resize-observer
eb691f9

github-actionsBot requested a deployment to storybook-preview-7335 December 16, 2025 19:22 Abandoned

mattcosta7 deployed to github-pages December 16, 2025 19:32 — with GitHub Actions View deployment

github-actionsBottemporarily deployed to storybook-preview-7335 December 16, 2025 19:33 Inactive

avoid mcoking in tests
45f06d2

mattcosta7 deployed to github-pages December 16, 2025 19:43 — with GitHub Actions View deployment

github-actionsBottemporarily deployed to storybook-preview-7335 December 16, 2025 19:44 Inactive

francinelucca approved these changes Dec 16, 2025
View reviewed changes

francinelucca added the integration-tests: skipped manually Changes in this PR do not require an integration test label Dec 16, 2025

siddharthkp removed the integration-tests: skipped manually Changes in this PR do not require an integration test label Dec 17, 2025

Merge branch 'main' into perf/use-resize-observer
efde70a

siddharthkp deployed to github-pages December 17, 2025 21:40 — with GitHub Actions View deployment

github-actionsBottemporarily deployed to storybook-preview-7335 December 17, 2025 21:40 Inactive

Merge branch 'main' into perf/use-resize-observer
64a0de0

mattcosta7 deployed to github-pages December 19, 2025 16:21 — with GitHub Actions View deployment

github-actionsBottemporarily deployed to storybook-preview-7335 December 19, 2025 16:22 Inactive

mattcosta7 changed the title ~~perf(hooks): Add first-immediate throttling to useResizeObserver and useOverflow~~perf(hooks): Add opt-in throttling to useResizeObserver and useOverflowDec 22, 2025

Merge branch 'main' into perf/use-resize-observer
b999a75

mattcosta7 deployed to github-pages December 30, 2025 19:12 — with GitHub Actions View deployment

github-actionsBottemporarily deployed to storybook-preview-7335 December 30, 2025 19:13 Inactive

mattcosta7 closed this Jan 12, 2026

primerBot deleted the perf/use-resize-observer branch June 30, 2026 18:10

Navigation Menu

Uh oh!

perf(hooks): Add opt-in throttling to useResizeObserver and useOverflow - #7335

perf(hooks): Add opt-in throttling to useResizeObserver and useOverflow#7335
mattcosta7 wants to merge 9 commits into
mainfrom
perf/use-resize-observer

mattcosta7 commented Dec 15, 2025•
edited
Loading

Uh oh!

changeset-botBot commented Dec 15, 2025•
edited
Loading

Uh oh!

github-actionsBot commented Dec 15, 2025

Uh oh!

mattcosta7Dec 15, 2025•
edited
Loading

Uh oh!

CopilotAI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

francinelucca left a comment

Uh oh!

Uh oh!

Uh oh!

primer-integrationBot commented Dec 22, 2025

Uh oh!

primer-integrationBot commented Dec 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

mattcosta7 commented Dec 15, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

API

Expected INP Impact (when throttle=true)

Why opt-in?

Why this matters

Uh oh!

changeset-botBot commented Dec 15, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actionsBot commented Dec 15, 2025

Uh oh!

mattcosta7Dec 15, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

francinelucca left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

primer-integrationBot commented Dec 22, 2025

Uh oh!

primer-integrationBot commented Dec 22, 2025

🔬 github-ui Integration Test Results

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mattcosta7 commented Dec 15, 2025•
edited
Loading

changeset-botBot commented Dec 15, 2025•
edited
Loading

mattcosta7Dec 15, 2025•
edited
Loading