After I Closed the Image Viewer with Esc, the Page Behind It Stopped Scrolling: What I Counted When Moving to the dialog Element

Moving to the dialog element removed the keyboard problems

For the keyboard and the background, relying on the browser was more dependable than writing it myself. A dialog opened with showModal() gives you these by default.

• Esc closes it
• The page behind becomes non-interactive, so Tab does not leave the dialog
• On close, focus returns to the element that had it before opening

This is the structure after the move. The close button goes into its own bar instead of sitting on the image.

<dialog class="lb" id="lb" aria-label="Enlarged image">
  <div class="lb-bar"><button id="close" type="button" aria-label="Close">×</button></div>
  <div class="lb-stage"><img id="big" alt=""></div>
</dialog>
 
<style>
  html{scrollbar-gutter:stable}
  body:has(dialog[open]){overflow:hidden}
 
  dialog.lb{border:0;padding:0;margin:0;width:100%;height:100%;
            max-width:none;max-height:none;background:rgba(0,0,0,.92);
            color:#fff;overscroll-behavior:contain}
  dialog.lb[open]{display:grid;grid-template-rows:auto minmax(0,1fr)}
  dialog.lb::backdrop{background:rgba(0,0,0,.92)}
 
  /* The close button goes outside the image area (in the top bar), not on the image */
  .lb-bar{display:flex;justify-content:flex-end;
          padding:max(8px,env(safe-area-inset-top)) max(8px,env(safe-area-inset-right)) 8px 8px}
  .lb-bar button{width:44px;height:44px;font-size:24px}
 
  /* The image fits the remaining area. Without minmax(0,1fr) a tall image pushes the row open */
  .lb-stage{min-height:0;display:grid;place-items:center;
            padding:0 max(8px,env(safe-area-inset-right))
                    max(8px,env(safe-area-inset-bottom))
                    max(8px,env(safe-area-inset-left))}
  .lb-stage img{max-width:100%;max-height:100%;width:auto;height:auto;
                object-fit:contain;display:block}
</style>
 
<script>
  const lb = document.getElementById('lb');
  const big = document.getElementById('big');
  document.querySelectorAll('[data-full]').forEach((b) => b.addEventListener('click', () => {
    big.src = b.dataset.full;
    big.alt = b.querySelector('img').alt;
    lb.showModal();
  }));
  document.getElementById('close').addEventListener('click', () => lb.close());
  // Also close when the margin (the dialog itself) is clicked, which is neither the image nor the bar
  lb.addEventListener('click', (e) => { if (e.target === lb) lb.close(); });
</script>

Each thumbnail is a button whose data-full holds the location of the large image. As a button it can be reached with Tab and opened with Enter.

The same script gave these numbers.

"2 of 4" is not a miss. Inside a dialog, Tab alternates between the close button and the browser's own interface, such as the address bar. While focus is outside the page, document.activeElement is body, so the count halves. What matters is that focus never reaches a thumbnail or link behind the dialog. In the old version, none of the four presses landed inside the viewer; focus stayed on the page behind it.

What I did not expect: scrolling after closing with Esc

I thought it was fixed. Then I wrote the background lock the "usual" way and a different bug appeared.

// The usual approach (Before): add a marker on open, remove it inside the close button
lb.showModal();
document.body.classList.add('lock');   // body.lock { overflow: hidden }
 
closeBtn.addEventListener('click', () => {
  lb.close();
  document.body.classList.remove('lock'); // <- Esc never goes through here
});

In the script's scrollAfterEsc, scrollY stayed at 0 after closing with Esc.

Esc closes a dialog through its cancel path, which never goes through the close button's handler. Only the lock class stays behind, and the page looks frozen. You will not hit that path if you only test with touch, so it is a bug that is easy to miss when you do not use the keyboard.

The fix was to stop toggling a marker by hand and let CSS read the state itself: is the dialog open right now.

/* After: lock the page only while a dialog is open, regardless of how it closes */
body:has(dialog[open]) { overflow: hidden; }

Whether it closes by the button, a click on the margin, Esc, or a call to lb.close(), the lock goes away the moment the open attribute does.

For a component that can be closed in several ways, attach cleanup to the closed state, not to the closing action. That was what I took away this time.

I stopped putting the close button in the same area as the image

There were other ways to reduce overlap: a smaller button, a shrunken image, a translucent background. But all of them assume that overlap will happen.

I reserved one row for a bar and fit the image into the remaining area, so the structure itself cannot overlap. The minmax(0, 1fr) in grid-template-rows: auto minmax(0, 1fr) is the key. Without it, a tall image pushes the row open and the bar can slide off screen.

The safe areas are added with env(safe-area-inset-*) and max() so the bar is not hidden on devices with a notch, but I could not verify that part in Chromium. The next section lists what these numbers cannot tell you.

What these numbers do not tell you

Every number here comes from Playwright's Chromium. These are outside what I checked.

• The behavior of WebKit (Safari on iPhone). It would not launch in my environment, so I did not run it
• The real safe-area margins. On a screen without a notch they are always 0
• The effect of scrollbar-gutter: stable. Headless scrollbars take no width, so I could not measure any layout shift

For what it is worth, I finish this kind of fix on a real device too. On my own site, opening one tall and one wide artwork in both phone orientations and checking the button position and scrolling after closing, by hand, was the deciding step. Counting with a script that nothing got worse, and then confirming on a device that it is pleasant to use, works well as two stages.

An instruction to give your agent

When I have an Antigravity agent build or fix an image viewer, I hand over the things to verify first rather than only the finished look.

Implement the image viewer with a dialog element (showModal) and meet these conditions.
1. Put the close button outside the image area (in a top bar) so it never overlaps the image
2. Lock background scrolling with body:has(dialog[open]) and do not toggle a class from JS
   (so the lock is released even when the dialog is closed with Esc)
3. Make thumbnails button elements that open with Tab and Enter
4. After implementing, report the results of lightbox-check.js (overlap, Tab, scrollY, Esc)
   using a tall image (800x2000) and a wide image (2400x900).
   If you could not check an item, say that you could not.

The last line reduces the cases where something that was not checked gets summarized as "no problem".

Pitfalls

• When you set display:grid on a dialog, limit it to dialog[open]. If you write it for plain dialog, closed dialogs show up too
• Set the default max-width and max-height of dialog to none, otherwise it will not be full screen
• When the image loads slowly, only the bar appears first. Adding width and height attributes to the img keeps the row height stable
• Adding z-index to the old structure will not fix the keyboard or the background scrolling. Those are separate problems from overlap

What to try next

Run your own viewer through lightbox-check.js and take the four numbers. Overlap shows up when you open tall and wide images in both phone orientations, and the Esc result is easiest to catch with a keyboard attached.

To avoid being misled when you check images, the steps for reading currentSrc and the rendered size on the real page are worth keeping nearby. If you also rewrite the URL, replaceState and relative paths for lazy images is a related check to run at the same time.

If you try the script on your own viewer, I would be glad to hear which of the four numbers surprised you.