Viewport meta tag: the line that makes a page mobile-friendly
Set the viewport meta tag to width=device-width, initial-scale=1, never user-scalable=no, then test mobile with Lighthouse and device mode.
LLaunchScaler·Published ·8 min read
The viewport meta tag is one line in your page's <head>: <meta name="viewport" content="width=device-width, initial-scale=1">. It tells a phone's browser to lay the page out at the device's own width, so your responsive CSS applies, instead of rendering a desktop-width page and shrinking it to fit.
Two values in that tag do real harm when added: user-scalable=no and a low maximum-scale such as maximum-scale=1. Both stop visitors zooming in, which fails WCAG's 200% resize requirement. Google's Mobile-Friendly Test is gone, so this guide also covers how to test a page on mobile with the tools that replaced it.
What does the viewport meta tag do?
It switches off the mobile browser's virtual desktop viewport. Without the tag, MDN explains, mobile browsers lay the page out in a virtual viewport wider than the screen, typically about 980 pixels, and shrink the result to fit. Media queries then see a 980-pixel page and your mobile layout never applies.
With width=device-width, the layout viewport matches the device's width in CSS pixels, so a phone that is 390 CSS pixels wide gets your 390-pixel layout. initial-scale=1 sets the starting zoom to 1:1, so the page opens at its designed size rather than zoomed out.
A template or layout file is the right place for it, so every page inherits it. If one page lacks it, that page alone renders as a shrunken desktop layout on phones.
Which values should the viewport tag contain?
Questions, answered
What people ask about this
01
What is the correct viewport meta tag?
Put a meta tag with name="viewport" and content="width=device-width, initial-scale=1" in the head of every page. It makes mobile browsers lay the page out at the device's width instead of a wide virtual viewport shrunk to fit.
For almost every site, only width=device-width and initial-scale=1. MDN lists the other keys a viewport tag accepts, and most of them either change nothing useful or take control away from the visitor. This table gives each key, what it does, and whether to use it.
Key
What it does
Use it?
width
Width of the layout viewport; device-width or 1 to 10000
Yes, as width=device-width
initial-scale
Starting zoom, 0.0 to 10.0
Yes, as initial-scale=1
maximum-scale
Highest zoom a visitor can reach
No; if you must set it, 5 or higher
minimum-scale
Lowest zoom a visitor can reach
Rarely needed
user-scalable
yes (default) or no; whether the visitor can zoom
Never set it to no
height
Height of the layout viewport
Rarely needed
interactive-widget
How the on-screen keyboard resizes the page: resizes-visual, resizes-content or overlays-content
Only for apps with fixed bottom UI
viewport-fit
How the page fills screens with notches: auto, contain or cover
cover only with safe-area CSS
Keep initial-scale at 1. Chrome's Lighthouse audit for this tag fails a page whose initial-scale is below 1, and explains why: a scale below 1 turns on double-tap zoom, which adds a 300 millisecond delay to every tap while the browser waits to see whether a second tap follows.
Why should you never use user-scalable=no?
Because people with low vision zoom to read. WCAG success criterion 1.4.4 (Level AA) requires that text can be resized up to 200 percent without assistive technology and without loss of content or functionality. user-scalable=no blocks pinch-zoom entirely, and maximum-scale=1 caps it at the starting size.
MDN's guidance goes further than the minimum: WCAG requires 2x scaling, and the best practice is to allow 5x. Automated checkers enforce it. Lighthouse's accessibility audit "[user-scalable="no"] is not used in the <meta name="viewport"> element and the [maximum-scale] attribute is not less than 5" carries a weight of 10 in its accessibility score, and Deque's axe rule "Zooming and scaling must not be disabled" fails any page with user-scalable=no or a maximum-scale below 2.
These values usually arrive in a copied template, or were added to hide a layout that breaks when zoomed. Neither is a reason to block zoom. Delete both values, then fix whatever breaks at high zoom, because that layout is also failing the Reflow criterion described below.
How do you set the viewport meta tag in Next.js?
Usually you don't. Next.js adds <meta name="viewport" content="width=device-width, initial-scale=1"> to every route by default, along with the charset tag, even if the route defines no metadata. You only touch it to change a value, and then you use the viewport export, not metadata.
To override it, export a viewport object from a layout.tsx or page.tsx:
import type { Viewport } from 'next'
export const viewport: Viewport = {
width: 'device-width',
initialScale: 1,
themeColor: '#ffffff',
}
Three rules from the Next.js documentation keep this working:
The viewport object and the generateViewport function are only supported in Server Components. A file that starts with 'use client' cannot export them.
You cannot export both viewport and generateViewport from the same route segment. Use generateViewport only when the value depends on request data.
The viewport option inside metadata has been deprecated since Next.js 14. If an older project still sets metadata.viewport, move it to the viewport export; Next.js has a metadata-to-viewport-export codemod for this.
One warning: the example in the Next.js docs for width, initialScale, maximumScale and userScalable sets maximumScale: 1 and userScalable: false, which outputs maximum-scale=1, user-scalable=no. It is there to show the fields, not as a recommendation. Do not copy those two lines.
How do you test mobile-friendliness now that Google's test is gone?
Use Chrome Lighthouse and DevTools device mode. Google's documentation changelog records that on 1 December 2023 it removed mentions of the Mobile-Friendly Test and the Mobile Usability report because both were going away. Its page experience guide now names Chrome Lighthouse as the tool for mobile usability improvements.
Run this sequence on each key page:
Open the page in Chrome, open DevTools and click Toggle device toolbar.
Choose the Mobile S preset (320 pixels), then Mobile M (375) and Mobile L (425). Scroll the whole page at each width and look for anything cut off, overlapping or wider than the screen.
In the Elements panel, check the <head> for exactly one viewport tag. If a theme and a plugin both add one, remove the extra so only the tag you intend is there.
Open the Lighthouse panel, select Mobile, and run the Accessibility and Best practices categories. Look for "Does not have a <meta name="viewport"> tag with width or initial-scale" and for the zoom rule.
On a desktop window 1280 pixels wide, zoom the browser to 400%. WCAG's Reflow criterion says 320 CSS pixels is equivalent to a 1280-pixel viewport at 400% zoom, and content must remain usable without scrolling in two directions.
Open the page on a real phone. Chrome describes device mode as a first-order approximation, not a real device.
What else makes a page fail on mobile?
The viewport tag lets your responsive CSS work; it does not make the CSS right. Three more checks catch most of the remaining failures, and each has a WCAG criterion behind it.
Check
The bar
How to test
Reflow
No horizontal scrolling at a width equivalent to 320 CSS pixels (WCAG 1.4.10, Level AA), except content that needs two dimensions, such as maps and data tables
Device toolbar at 320 px, or 400% zoom on a 1280 px window
Tap targets
Pointer targets at least 24 by 24 CSS pixels (WCAG 2.5.8, Level AA), unless a 24-pixel circle centred on each small target touches no other target, or another exception applies
Inspect small icons, close buttons and footer links; check their box size and spacing
Text resize
Text resizes to 200% without loss of content or functionality (WCAG 1.4.4)
Pinch-zoom on a phone; browser zoom to 200% on desktop
A common cause of reflow failures is a fixed width: an image, table, code block or embedded video with a pixel width wider than the screen. max-width: 100% on images and embeds, and horizontal scrolling inside a wrapper for wide tables, fix most of these. For buttons that fall off the screen or sit under a banner at narrow widths, the pre-launch CTA and form test walks through each control at 320 pixels.
Does the viewport meta tag affect SEO?
Indirectly, through how your page renders for Google's smartphone crawler. Google's mobile-first indexing documentation says Google uses the mobile version of a site's content, crawled with the smartphone agent, for indexing and ranking. If your page lacks the tag, the mobile version Google evaluates is a desktop layout shrunk to fit a phone.
Google's page experience guide asks "Does your content display well on mobile devices?" as one of its self-assessment questions. The viewport tag is not a ranking signal you can switch on, but a page that displays badly on phones fails that question for every mobile visitor. Mobile layout also feeds your Core Web Vitals, which are measured from real visits, phones included; the guide to a failed Core Web Vitals assessment covers those metrics. And before a launch sends traffic to a page, the checklist for a website ready for launch traffic puts mobile rendering next to caching and forms.
Check your viewport and mobile layout in one scan
To check the tag and the layout it produces without opening DevTools, run the free scan. LaunchScaler renders your page in a real browser and runs 156 checks across 6 of its 7 categories with no account. Its speed and visual checks include "Viewport meta present but non-standard" (missing width=device-width, or extra values), "Pinch-zoom disabled by viewport meta", "Tap targets smaller than 24x24 CSS px", "Layout breakage across common viewports" at 320, 360, 390, 768, 1024 and 1440 pixels, and "Content clipped at 400% zoom". Fix what it flags, then confirm on one real phone.
No. Both stop people pinch-zooming, and WCAG 1.4.4 requires that text can be resized to 200% without loss of content. MDN recommends allowing zoom to 5x, and Lighthouse fails a maximum-scale below 5.
03
How do I set the viewport meta tag in Next.js?
You usually do not need to. Next.js adds width=device-width, initial-scale=1 to every route by default. To change it, export a viewport object or a generateViewport function from a layout or page that is a Server Component.
04
Is Google's Mobile-Friendly Test still available?
No. Google retired the Mobile-Friendly Test and the Mobile Usability report in December 2023. Its page experience guide now points to Chrome Lighthouse for mobile usability.
05
Does the viewport meta tag affect SEO?
Indirectly. Google indexes and ranks the mobile version of a page, crawled with its smartphone agent, so a page that renders as a shrunken desktop layout is what Google evaluates. The tag is what lets your responsive CSS apply.
AVIF is usually smaller than WebP at the same quality but encodes more slowly. All major browsers now support both, so serve AVIF with a WebP fallback.
