Viewport

What is the viewport?

The viewport is the area of a web page that is visible to the user. On a desktop it is the browser window's content area, on a phone it is the screen, and it changes when the user rotates the device, resizes the window or zooms. Your CSS lays out against the viewport width, so getting it right is the foundation of mobile-first design and responsive layouts.

Layout viewport and visual viewport

Browsers actually track two viewports (MDN's Visual Viewport API page):

• Layout viewport: covers all the elements of the page. It does not change when the user pinch-zooms.
• Visual viewport: the part of the page currently on screen. It shrinks when the user pinch-zooms in, and the on-screen keyboard can shrink it without touching the layout viewport.

This is why a fixed-position bar can end up hidden behind the keyboard. Scripts can read the visual viewport through window.visualViewport (width, height, scale, offsetTop), which MDN lists as widely available since August 2021.

The meta viewport tag

Mobile browsers often render a page in a wider virtual viewport (MDN gives 980px on a 640px screen) and scale it down, so your media queries see the wrong width. The viewport meta tag fixes that. MDN's recommended value is:

<meta name="viewport" content="width=device-width">

Most sites also add initial-scale=1, which MDN says is usually unnecessary but harmless if you want the page to start at 100% zoom. The other directives:

Viewport units

The viewport sets the base for vw (1% of the viewport width) and vh (1% of its height). MDN notes that when the viewport resizes, the computed size of these units changes with it. Width in the meta tag is the basis for vw.

Never block zoom

Setting user-scalable=no stops people with low vision from enlarging the page. MDN warns that this "prevents people experiencing low vision conditions from being able to read and understand page content", that WCAG requires a minimum of 2x scaling, and that the best practice is to allow 5x. Two WCAG success criteria apply: 1.4.4 Resize Text (text can be resized up to 200 percent without loss of content or functionality) and 1.4.10 Reflow (content works at a width equivalent to 320 CSS pixels without scrolling in two dimensions). Browsers may also ignore these settings: MDN notes iOS 10 and later ignore user-scalable, minimum-scale and maximum-scale by default. See WCAG and accessible layouts for the wider picture.

Common mistakes

• No viewport meta tag. The page renders in a wide virtual viewport and looks tiny on a phone.
• Disabling zoom with user-scalable=no or a low maximum-scale. It fails low-vision users and is not needed to prevent layout bugs.
• Fixed pixel widths. Elements wider than the viewport cause horizontal scrolling and break reflow.
• Tying a layout to vh alone. The visible height changes with browser toolbars and the keyboard. Test with the keyboard open.
• Testing only on desktop. Resize the window or use your browser's device mode, then check a real phone.

Viewport and performance testing

Viewport size decides which media queries match and which image your page loads, so desktop and mobile runs can load different content. LoadFocus page speed monitoring runs Lighthouse audits for desktop and mobile from 25 cloud regions, so you can compare the two and track Core Web Vitals over time. Mobile-specific advice is also in our guide to improving website speed. References: MDN on the viewport meta tag and the Visual Viewport API.

FAQ: Viewport

What does width=device-width do?

It sets the layout viewport width to the device's screen width in CSS pixels, so the page is not rendered in a wider virtual viewport and scaled down.

Is user-scalable=no allowed?

Technically yes, but it blocks pinch zoom and harms low-vision users. MDN says WCAG requires at least 2x scaling and recommends allowing 5x. Leave zoom enabled.

What is the difference between the layout and visual viewport?

The layout viewport is the area your CSS lays out against and it stays put when users pinch-zoom. The visual viewport is the part currently visible on screen and shrinks when they zoom or when the on-screen keyboard appears.

Do I need initial-scale=1?

Often not. MDN says it is usually unnecessary, but it is harmless if you want the page to start at 100% zoom. Avoid horizontal overflow in the first place.

How do I test different viewports?

Resize the browser window, use the device toolbar in your browser's developer tools, and confirm on a real device. Lab tools such as Lighthouse also test mobile and desktop separately.