The Viewport Meta Tag: A Complete Guide (with theme-color)
Understand with AI
Discuss with your preferred AI assistant
Most web traffic is now mobile, so a broken viewport tag degrades the experience for the majority of visitors.
Disabling zoom violates WCAG 2.1 Resize Text, which requires content to scale to 200% without loss of function.
Google indexes the mobile version of your pages first, making a correct viewport tag essential for rankings.
The viewport meta tag is one line of HTML, yet it decides whether your site renders correctly on a phone or shows up as a tiny, zoomed-out desktop layout that nobody can read. It is the single most important tag for mobile-friendliness, and since Google moved to mobile-first indexing, it directly affects how your pages rank.
This guide explains exactly what the viewport meta tag does, every property it supports, the modern theme-color tag that styles the browser UI, and the common mistakes that quietly break responsiveness or accessibility. By the end you will know precisely which tag to ship.
What Is the Viewport Meta Tag?
The viewport is the visible area of a web page on a device. The viewport meta tag tells the browser how to control that area's dimensions and scaling. Without it, mobile browsers assume a desktop-sized canvas (typically 980px wide) and shrink the whole page to fit, leaving text unreadable and tap targets microscopic.
The canonical, responsive version looks like this:
- width=device-width — match the layout width to the device's screen width in CSS pixels.
- initial-scale=1 — render at a 1:1 zoom level on first load, so one CSS pixel equals one device-independent pixel.
Together, these two values are what make a CSS media-query layout behave as designed on real devices.
Every Viewport Property Explained
The content attribute is a comma-separated list of directives. These are the ones that matter:
| Property | What it does | Recommended |
|---|---|---|
| width | Sets viewport width. Use device-width for responsive sites, or a number for a fixed canvas. | device-width |
| initial-scale | Zoom level when the page first loads (0.1–10). | 1 |
| maximum-scale | The largest zoom the user may reach. Often misused to block zoom. | Omit, or ≥ 2 |
| minimum-scale | The smallest zoom allowed. | Omit |
| user-scalable | yes allows pinch-zoom; no blocks it. | yes |
The theme-color Meta Tag
The theme-color meta tag tints the browser's UI — the address bar on Chrome for Android, the status bar area in installed PWAs, and surrounding chrome — to match your brand. It is a small touch that makes a site feel native and polished.
Modern browsers also support a media attribute so you can serve different colors for light and dark mode:
- A single tag applies one color everywhere.
- Two tags with media="(prefers-color-scheme: light)" and media="(prefers-color-scheme: dark)" let the browser pick the right tint automatically.
Accessibility: Never Disable Zoom
The most damaging mistake developers make is setting user-scalable=no or maximum-scale=1 to "lock" the layout. This blocks pinch-to-zoom and fails WCAG 2.1 Success Criterion 1.4.4 (Resize Text), which requires content to scale to at least 200% without loss of function. Users with low vision rely on zoom; removing it can make a site legally inaccessible.
The good news: modern iOS Safari ignores these restrictions entirely, and there is almost never a real reason to disable zoom. Leave it enabled. Our generator flags any setting that breaks this rule before you ship it.
How to Use the Generated Tag
Plain HTML
Paste the generated <meta> tags into the <head> of every page, ideally near the very top so the browser reads them before laying out content.
React and Next.js
In the Next.js App Router, do not hand-write the tag — export a typed viewport object from your layout and let the framework render it. Our tool outputs that export for you alongside the raw HTML and JSX versions.
Expert Tips
Keep zoom enabled, always
Resist the urge to lock zoom with user-scalable=no. It breaks accessibility, fails WCAG, and modern iOS Safari ignores it anyway. The default — pinch-zoom on — is the right call.
Use light + dark theme colors
Provide two theme-color tags with prefers-color-scheme media queries so the browser chrome matches the user system theme. It is a small detail that makes your site feel native and intentional.
Frequently Asked Questions
What is the correct viewport meta tag?
For responsive sites the correct tag is <meta name="viewport" content="width=device-width, initial-scale=1"> . This matches the layout to the device width and renders at 1:1 zoom, which is what CSS media queries expect.
Should I set maximum-scale or user-scalable=no?
No. Restricting zoom fails WCAG 2.1 accessibility guidelines and harms users with low vision. Modern iOS Safari ignores these directives anyway. Leave pinch-zoom enabled unless you have a very specific, well-justified reason.
What does the theme-color meta tag do?
It tells supporting browsers (notably Chrome on Android and installed PWAs) what color to tint their UI chrome. You can provide separate light and dark colors using the media attribute so the tint follows the user's system theme.
Does the viewport meta tag affect SEO?
Indirectly but significantly. Google uses mobile-first indexing, and a missing or broken viewport tag makes pages fail the mobile-friendly check, hurting rankings and Core Web Vitals. A correct tag is a baseline requirement for mobile SEO.