[useScrollLock] Reduce style recalculation with classic scrollbars by mdm317 · Pull Request #3854 · mui/base-ui

mdm317 · 2026-01-24T16:19:04Z

I have followed (at least) the PR section of the contributing guide.

Current

When using classic (inset) scrollbars with scroll locking, full document recalc can occur.

[Chromium 143]

3 full document recalc

[Chromium 144]

1 full document recalc

Cause

Directly changing <html> styles causes a full document style recalculation.

Solution

When checking scrollbar gutter stable, use body by default, except in cases where overflow-y: scroll is set on <html>.

Test

Verified scroll locking works correctly.
- Preview link
  - should check both classic and overlay scrollbars.

Improve

[Chromium 143]

1 full document recalc (Because we shoud set scrollbar-gutter in html)

[Chromium 144]

0 full document recalc

Limitation

Improving this behavior is not feasible for users who set overflow-y: scroll on <html>.

pkg-pr-new · 2026-01-24T16:20:16Z

base-ui-tanstack-start

vite-css-base-ui-example

pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/react@3854

pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/utils@3854

commit: 46bbbcd

mui-bot · 2026-01-24T16:20:32Z

Bundle size report

Bundle	Parsed size	Gzip size
@base-ui/react	🔺+104B^(+0.02%)	🔺+34B^(+0.03%)

Details of bundle changes

Check out the code infra dashboard for more information about this PR.

netlify · 2026-01-24T16:21:47Z

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	`46bbbcd`
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/6982e28449842800087edc20
😎 Deploy Preview	https://deploy-preview-3854--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

mdm317 · 2026-01-25T02:03:21Z

packages/utils/src/useScrollLock.ts

+    overflowY: scrollContainer.style.overflowY,
  };

  html.style.scrollbarGutter = 'stable';


scrollbar-gutter works as expected on the html element.
check blog css-overflow-3-spec

mdm317 · 2026-01-25T02:05:42Z

docs/src/app/(private)/experiments/scroll-lock.tsx

 export default function ScrollLock() {
  const [enabled, setEnabled] = React.useState(false);
  const [bodyScrollY, setBodyScrollY] = React.useState(false);
+  const [htmlScrollY, setHtmlScrollY] = React.useState(false);


Add htmlScrollY to ensure scroll blocking works correctly when overflow-y: scroll is set on .

This reverts commit 3806559.

atomiks · 2026-01-27T20:47:47Z

@greptileai

greptile-apps · 2026-01-27T20:50:27Z

Greptile Overview

Greptile Summary

Improved performance of scroll locking with classic scrollbars by minimizing full document style recalculations. The optimization detects the appropriate scroll container (body vs html) and applies changes there instead of always modifying html directly, reducing recalculations from 3 to 1 (Chromium 143) or 1 to 0 (Chromium 144).

Key changes:

Modified supportsStableScrollbarGutter() to test scrollbar behavior on the actual scroll container (body by default, html only when it has overflow)
Updated preventScrollOverlayScrollbars() to save/restore overflowX and overflowY separately instead of combined overflow property
Added test controls for html overflow case to verify the documented limitation

The implementation correctly handles state restoration for both html and body elements.

Confidence Score: 5/5

This PR is safe to merge with minimal risk
The changes are well-targeted performance optimizations with clear benefits. The logic correctly handles state restoration for both scroll containers, the previous thread issue has been addressed, and the implementation maintains backward compatibility while reducing layout thrashing.
No files require special attention

Important Files Changed

Filename	Overview
packages/utils/src/useScrollLock.ts	Optimized scrollbar gutter detection to use body instead of html when possible, reducing full document recalculations
docs/src/app/(private)/experiments/scroll-lock.tsx	Added html overflow checkbox to test edge case where optimization doesn't apply

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-27T20:50:31Z

packages/utils/src/useScrollLock.ts

+    overflowY: scrollContainer.style.overflowY,
  };

  html.style.scrollbarGutter = 'stable';


scrollbarGutter set on html but saved/restored on scrollContainer. When scrollContainer is body, this leaves html.style.scrollbarGutter = 'stable' permanently set.

Suggested change

html.style.scrollbarGutter = 'stable';

scrollContainer.style.scrollbarGutter = 'stable';

Prompt To Fix With AI

This is a comment left during a code review. Path: packages/utils/src/useScrollLock.ts Line: 42:42 Comment: `scrollbarGutter` set on `html` but saved/restored on `scrollContainer`. When `scrollContainer` is `body`, this leaves `html.style.scrollbarGutter = 'stable'` permanently set. ```suggestion scrollContainer.style.scrollbarGutter = 'stable'; ``` How can I resolve this? If you propose a fix, please make it concise.

I've fixed it.

atomiks · 2026-01-30T09:54:58Z

In the demo when Long content is unchecked, the scrollbar disappears (differing from master) - enabling scroll lock then shifts the content

mdm317 · 2026-01-31T16:32:37Z

I missed that case — thanks for pointing it out. 😔

In the demo when Long content is unchecked, the scrollbar disappears

This difference comes from how the demo is configured:

In the demo(master), overflow-y: scroll is applied via a class on the html element.
In the demo(current), overflow-y: scroll is instead added as a class on the body.
Also, for testing purposes, when neither body nor html has an overflow property, i temporarily set overflow-y: visible inline style. diff

This happens in the demo(master) as well if you manually disable overflow-y: scroll on html.
So when both body and html have no overflow: scroll and the Long content is unchecked, there is no scrollbar.

enabling scroll lock then shifts the content

The layout shift issue occurs when preventScrollOverlayScrollbars is used.
When scroll lock is released, the previously set inline overflow-y: visible is not restored correctly, which results shift.

I fixed this issue in this commit.

So in the current demo, whenLong content is unchecked and neither body nor html has overflow: scroll set, the scrollbar disappears.
Unlocking scroll lock also keeps the scrollbar hidden, so the content doesn’t shift.

atomiks

Nice, wasn't able to find any new issues with the latest implementation

…hing

atomiks · 2026-02-04T06:13:04Z

@greptileai

mdm317 added 4 commits January 24, 2026 22:38

feat

73f7d58

test code

58bc562

remove log

f95925b

refactor

8696bda

mdm317 commented Jan 25, 2026

View reviewed changes

mdm317 added 2 commits January 25, 2026 20:51

fix test code

3806559

Revert "fix test code"

c5b2b06

This reverts commit 3806559.

mdm317 marked this pull request as ready for review January 25, 2026 12:10

mdm317 requested review from atomiks, colmtuite and michaldudak as code owners January 25, 2026 12:10

This comment was marked as outdated.

Sign in to view

oliviertassinari changed the title ~~[useScrollLock]: reduce style recalculation with classic scrollbars~~ [useScrollLock] Reduce style recalculation with classic scrollbars Jan 25, 2026

oliviertassinari added the performance label Jan 25, 2026

atomiks added the package: utils Specific to the utils package. label Jan 27, 2026

greptile-apps bot reviewed Jan 27, 2026

View reviewed changes

refactor

a68b0f8

fix : overlay scrollbar lock not restoring overflow styles

13a5f27

atomiks approved these changes Feb 4, 2026

View reviewed changes

Merge branch 'master' into perf/classic-scrollbar-reduce-layout-thras…

46bbbcd

…hing

atomiks merged commit 93a3862 into mui:master Feb 4, 2026
24 checks passed

	html.style.scrollbarGutter = 'stable';
	scrollContainer.style.scrollbarGutter = 'stable';

Uh oh!

Conversation

mdm317 commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Current

[Chromium 143]

[Chromium 144]

Cause

Solution

Test

Improve

[Chromium 143]

[Chromium 144]

Limitation

Uh oh!

pkg-pr-new bot commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mui-bot commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle size report

Uh oh!

netlify bot commented Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for base-ui ready!

Uh oh!

mdm317 Jan 25, 2026 • 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!

mdm317 Jan 25, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

atomiks commented Jan 27, 2026

Uh oh!

greptile-apps bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Overview

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

mdm317 Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

atomiks commented Jan 30, 2026

Uh oh!

mdm317 commented Jan 31, 2026

Uh oh!

atomiks left a comment

Choose a reason for hiding this comment

Uh oh!

atomiks commented Feb 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mdm317 commented Jan 24, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 24, 2026 •

edited

Loading

mui-bot commented Jan 24, 2026 •

edited

Loading

netlify bot commented Jan 24, 2026 •

edited

Loading

mdm317 Jan 25, 2026 •

edited

Loading

greptile-apps bot commented Jan 27, 2026 •

edited

Loading