deadheadmissing meta viewport
Without a viewport meta tag, mobile browsers lay the page out at a desktop width of about 980px and shrink it to fit.
- Avoid
- Harmful
- Severity
- HarmfulActively breaks something for users.
- Basis
- Browser conventionEvery engine agrees, but nothing normative says so.
- Detectable
- YesMatched exactly. Autofixable when the rule carries a fix.
- Matches
logic moduleDocument rule, inside <head>.- Fix
- None — reports only
- Impacts
- Accessibility and Interoperability
- Related
meta/viewport-user-scalable
A page with no <meta name="viewport"> tells a mobile browser nothing about how wide to
lay it out, and the browser assumes the worst: a desktop page, written before phones
existed. So it renders the page in a virtual window about 980 pixels wide and shrinks the
result onto a screen a third of that.
Why avoid
Everything responsive stops working. MDN describes the fallback plainly: mobile browsers
render “in a virtual window or viewport that is wider than the screen (e.g., 980px), then
shrink the rendered result to fit”, and that mechanism “breaks responsive design techniques
using media queries”. A max-width: 600px breakpoint never fires, because as far as CSS
is concerned the viewport is 980px wide. The phone gets the desktop layout at a fraction of
its size.
The people using it pay for that directly. Text renders too small to read, so every page becomes pinch, zoom and pan, sideways as well as down. Google’s Lighthouse fails a page without the tag for exactly this reason: mobile devices “render pages at typical desktop screen widths and then scale the pages down, making them difficult to read”. It is one line of markup, and leaving it out undoes all the CSS that follows.
Use instead
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>…</title>
</head>width=device-width sets the layout viewport to the screen’s width in device-independent
pixels, so media queries and vw units mean what they say. initial-scale=1 sets a 1:1
ratio between CSS pixels and those device pixels in either orientation. Don’t add
user-scalable=no or a low maximum-scale to it (see meta/viewport-user-scalable).
A page that really is desktop-only, like an internal admin tool, an iframe-only embed or an
HTML email body, can go without. Say so where it happens:
<!-- deadhead-disable head/viewport -->.
Detectability
Fully detectable, as a document rule, because the finding is about an element that isn’t
there. It lands on <head>. A viewport <meta> anywhere in the document counts, since
browsers apply one even when it’s misplaced in <body>. Presence is all this checks: a
viewport without width=device-width is a different problem.
Nothing is reported unless there is a <head> with at least one element in it. Fragments,
partials and component templates aren’t whole documents, and shouldn’t be told to add a
tag that belongs to the page around them. One edge remains: a file with head content but no
<head> tag, like <!doctype html><title>…, is reported by the CLI without a line
number and not by the ESLint plugin, because only the CLI’s parser invents the missing head.
There is no autofix. The remedy adds an element, and every fix here only removes.
Resources
- MDN —
<meta name="viewport">— the ~980px virtual viewport, shrink-to-fit, and how it breaks media queries. - web.dev — Responsive web design basics: set the viewport — desktop-width rendering without the tag; what
width=device-widthandinitial-scale=1each do. - Chrome for Developers — Lighthouse: viewport meta tag — pages without the tag are “difficult to read”; the audit’s failure conditions.
- CSS Viewport Module Level 1 — viewport meta — the tag as written down by the CSS Working Group.
This page is generated from content/rules/head/viewport.md, the same file the linter is built from. Think the rule is wrong, or that browsers moved on? Say so — that is the most useful issue you can file.