Learning center

Report the viewport and zoom, not the screen resolution

"1920 × 1080" is the most common answer to "what is your screen size?" and rarely what a layout bug depends on. The page lays out in CSS pixels inside the browser window, at the browser's zoom level, at the display's pixel ratio. A maintainer with the same monitor and a different window or zoom sees a different layout. Ask for the numbers the page sees.

The numbers that decide layout#

ValueRead it withDepends on
Viewport width and height in CSS pixelsinnerWidth, innerHeight; document.documentElement.clientWidth excludes the scrollbarWindow size, browser zoom, OS display scaling
Device pixel ratiodevicePixelRatioDisplay density and browser zoom
Scrollbar widthinnerWidth - document.documentElement.clientWidthOS and its settings: overlay scrollbars take no width
Visual viewportvisualViewport.width, visualViewport.scalePinch zoom and the on-screen keyboard on touch devices

Ask the reporter to run this on the page and paste the result:

({ inner: [innerWidth, innerHeight], client: [document.documentElement.clientWidth, document.documentElement.clientHeight],
   dpr: devicePixelRatio, visual: visualViewport && [visualViewport.width, visualViewport.height, visualViewport.scale],
   screen: [screen.width, screen.height] })

screen is in the list so you can see how far it is from the viewport.

Browser zoom changes all of them#

In Chrome and Firefox, page zoom changes the size of a CSS pixel. At 125% zoom on a display with a pixel ratio of 1, devicePixelRatio becomes 1.25 and a 1600-pixel-wide window reports an innerWidth of 1280. Media queries respond to the smaller width. A user who zoomed to read more comfortably can therefore get the tablet layout on a desktop monitor. Zoom is remembered per site, so they may not remember setting it. MDN: Window.devicePixelRatio

Operating system display scaling does the same at the system level: a laptop at 150% scaling reports devicePixelRatio 1.5 at 100% browser zoom.

Replay the reporter's viewport#

Set the viewport and pixel ratio, not the window size:

const context = await browser.newContext({
  viewport: { width: 1280, height: 615 },
  deviceScaleFactor: 1.25,
});

In Chrome DevTools, device mode's Responsive preset takes a width, height and device pixel ratio. A pixel ratio can be fractional, such as 1.25 or 1.5, and fractional ratios are where 1-pixel borders and rounding bugs appear. Playwright: Viewport

Emulating the pixel ratio reproduces layout and image selection. It does not reproduce the reporter's font rendering or their OS's scrollbars.

Worked example: a hidden menu at 110%#

This example is fictional. A user reports that the account menu is missing from the header. The developer, on the same 1920-pixel monitor, sees it.

The user's capture shows inner: [1745, 880] and dpr: 1.1. Their browser was at 110% zoom for the site. At 1745 CSS pixels, the header switched to a layout that moved the account menu into a hamburger menu, but the hamburger button was hidden by a second media query written for max-width: 1760px. The two breakpoints overlapped for 15 pixels. Replaying with a viewport 1745 pixels wide showed the gap, and so did any window width in that 15-pixel band at 100% zoom.

Questions#

Is the window size useful at all?

As context. outerWidth minus innerWidth shows whether a side panel, such as DevTools or a reading list, was open. The viewport is what the layout used.

Do Safari and Chrome behave the same with zoom?

Safari's page zoom also reflows the layout, and its effect on devicePixelRatio differs. Read the values in the reporter's browser rather than assuming.

What about text size settings?

A larger default font size in the browser's settings changes rem and em sizes without changing the viewport. Ask for getComputedStyle(document.documentElement).fontSize when text-related layout breaks.

Return to reproducing what someone else saw for the other layers a replay needs.

One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. Eligibility and fair-use terms.

Start free with GitHub

Related reading