Modal popups write `--scrollbar-width` on `<html>` even when it is `0px`, so each close restyles the whole page again when the exit ends

Open Beginner friendly
#809 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
82/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
react, typescript

Research direction

Read packages/core/src/foundation/popups/modal.ts around freezeScroller and scrollLockStyles; the issue reports that --scrollbar-width is written even when the measured gutter is zero. Check the existing modal popup tests for coverage of scroll locking, then verify the lock avoids a root custom-property write when there is no gutter while preserving compensation when there is one.

Written by the indexing model from the issue text.

Description

What happens

A modal popup (modal true: Dialog, AlertDialog, Drawer, and a Menu, Select or Popover with modal) locks the page scroll. freezeScroller (packages/core/src/foundation/popups/modal.ts:80-99) writes overflow and scroll-behavior on the scroller. It also always writes --scrollbar-width: <gutter>px on <html>, even when the gutter is 0. The gutter is 0 on touch screens, with overlay scrollbars, and on pages whose document does not scroll. Releasing the lock removes the property again.

--scrollbar-width is an inherited custom property on the root. Adding, changing or removing it restyles every element in the document. Writing overflow on <html> does not.

The open and the close pay for it differently:

  • Open. freezePage (popup.ts:1140-1162) runs the lock and inertOutside in the same task, a paint after the open (afterPaint, :1175). The variable shares the whole-page restyle that inert causes anyway.
  • Close. inert is released in the press task (popup.ts:749). The lock is released only by thawPage (:1163-1171), a cleanup that runs when the exit animation ends (:1212). So the variable is removed alone, and the last frame of every close restyles the whole page a second time, for a value that was 0px all along.
Minimal reproduction

A page with about 1,800 elements and about 2,000 style rules, like an app screen. A Drawer stays mounted and opens on press. ?variant=trap-focus is the same Drawer with modal="trap-focus", so it has no lock and no inert.

// page.tsx
const tones = ["#111", "#333", "#555", "oklch(0.4 0.1 250)"]
const rules: string[] = ["@layer base, components, utilities;", "@layer components {"]
for (let i = 0; i < 300; i++) {
  rules.push(`.card[data-tone="${i % 7}"] .c${i} { color: oklch(0.5 0.2 ${i}); border-color: color-mix(in oklch, currentColor ${(i % 50) + 10}%, transparent); }`)
  rules.push(`.card:hover > .c${i}, .card:focus-within .c${i} { background-color: #fff; }`)
}
rules.push("}", "@layer utilities {")
for (let i = 0; i < 1500; i++) rules.push(`.u${i} { color: ${tones[i % 4]}; padding: ${i % 9}px; }`)
rules.push("}", ".row { display: flex; gap: 8px; padding: 4px 12px; border-bottom: 1px solid #ddd; }")
document.head.append(Object.assign(document.createElement("style"), { textContent: rules.join("\n") }))

const u = (i: number, k: number) => `u${(i * 37 + k * 101) % 1500} u${(i * 13 + k * 7) % 1500} c${(i + k) % 300}`

export const page = Array.from({ length: 300 }, (_, i) => (
  <div key={i} className={`row card ${u(i, 0)}`} data-tone={i % 7}>
    <div className={u(i, 1)}><span className={u(i, 2)}>{i % 9}</span></div>
    <div className={u(i, 3)}><span className={u(i, 4)}>row {i}</span><b className={u(i, 5)}>{i % 13}</b></div>
  </div>
))
// app.tsx
import { createRoot } from "react-dom/client"
import { Drawer, DrawerBackdrop, DrawerClose, DrawerContent, DrawerTitle, DrawerTrigger } from "@ui-sdk/react/drawer"
import "@ui-sdk/core/web.css"
import { page } from "./page"

const modal = new URLSearchParams(location.search).get("variant") === "trap-focus" ? "trap-focus" : true

function App() {
  return (
    <>
      <Drawer modal={modal}>
        <DrawerTrigger id="open">Open</DrawerTrigger>
        <DrawerBackdrop style={{ position: "fixed", inset: 0, background: "rgb(0 0 0 / 0.4)" }} />
        <DrawerContent style={{ background: "#fff", padding: 16 }}>
          <DrawerTitle>Drawer</DrawerTitle>
          <DrawerClose id="close">Close</DrawerClose>
          {Array.from({ length: 40 }, (_, i) => <p key={i}>Item {i}</p>)}
        </DrawerContent>
      </Drawer>
      <main>{page}</main>
    </>
  )
}

createRoot(document.getElementById("root")!).render(<App />)

Open and close the Drawer, then watch <html style>. The close removes overflow: hidden; scroll-behavior: auto; --scrollbar-width: 0px in the task that calls hidePopover at the end of the exit.

Measured

Playwright 1.64.1, viewport 390x844, DPR 3, touch, production React build. Chromium 156.0.8078.4 runs with the CPU throttled 4x; WebKit 27.2 (Linux) runs unthrottled. The page has about 1,800 elements. Each run starts in a fresh context and does open, close, open, close; the numbers are for the second close. fixed is beta.7 with the first change under Suggested direction.

Cost of one write followed by a read (document.body.offsetHeight) on this page. Median of 9 writes in each of 5 contexts:

Write on <html> Chromium 4x WebKit
add or remove --scrollbar-width: 0px 3.7 ms 10 ms
set --scrollbar-width to the value it already has 0 ms 0 ms
overflow: hidden on and off 0 ms 0 ms
for comparison: inert on <main> 3.5 ms 9 ms

Longest frame in the three frames after the exit ends, the frame where the lock is released. Median of 9 runs:

Chromium 4x WebKit
modal (beta.7) 22.8 ms (21.3-24.0) 24 ms (22-28)
modal, fixed 17.9 ms (17.5-19.7) 16 ms (16-18)
modal="trap-focus", no lock 17.4 ms (16.2-17.8) 16 ms (16-17)

The slowest fixed run is still faster than the fastest beta.7 run, in both engines. The Chromium trace (disabled-by-default-devtools.timeline.stack) of that task shows an UpdateLayoutTree of 7.3 ms with beta.7 and 2.0 ms with fixed. The task takes 21.3 ms and 16.6 ms. <html style> changes 3 times at the end of the exit with beta.7 and twice with fixed.

The open doesn't change measurably. The restyle in the frame after the open is 7.0 ms with beta.7 and 5.5 ms with fixed, because inert dominates it. Input to next paint is 29.1 and 27.9 ms in Chromium, 15 and 14 ms in WebKit.

The cost grows with the page and its styles, not with the popup. On an app screen of about 2,900 elements, the same root custom property write measured 50-64 ms in WebKit.

Expected

A close restyles the page at most once. When there is no gutter to compensate, the lock doesn't touch an inherited property on the root.

Suggested direction
  • Write --scrollbar-width only when the gutter is greater than 0, as padding-right and scrollbar-gutter already are in scrollLockStyles. A fixed header that pads itself by var(--scrollbar-width, 0px) gets the same 0 either way. This is the change measured above (fixed):

    -  restores.push(
    -    setStyle(
    -      doc.documentElement,
    -      "--scrollbar-width",
    -      `${Math.max(0, gutter)}px`
    -    )
    -  )
    +  if (gutter > 0) {
    +    restores.push(setStyle(doc.documentElement, "--scrollbar-width", `${gutter}px`))
    +  }
    
  • If the hook must always be set, set it once and keep it, rewriting it only when the gutter changes. Writing the same value again costs nothing: setProperty with an unchanged value measured 0 ms in both engines.

  • The hook is public according to the comment at modal.ts:91, but it isn't documented. The docs could name it, along with its fallback when there is no gutter.

Version

@ui-sdk/core and @ui-sdk/react 0.1.0-beta.7 (published dist/foundation/popups/modal.js:53-71, dist/foundation/popups/popup.js:328 release of inert, :619-645 freezePage/thawPage, :677 cleanup), source lines from main at 10b3b6c. React 19.3.1, Chromium 156.0.8078.4 and WebKit 27.2 (Playwright 1.64.1).

Dominant language
TypeScript
Stars
4.4k
Forks
122
Avg merge
3h 56m
Merged PRs (30d)
556

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from vercel-labs/ui

All issues in vercel-labs/ui

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.