{
    "slug": "viewport_meta_tag",
    "term": "Viewport Meta Tag",
    "category": "mobile",
    "difficulty": "beginner",
    "short": "An HTML meta tag that tells mobile browsers how to scale and size the layout viewport, controlling zoom and rendering width.",
    "long": "The viewport meta tag is a single HTML element placed in the document head that instructs mobile browsers how to control the page's dimensions and scaling. Without it, mobile browsers assume a desktop-width layout viewport (typically 980px) and shrink the rendered page to fit the screen, forcing users to pinch-zoom and scroll horizontally. The canonical declaration is `<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">`, which sets the layout viewport to match the device's screen width in CSS pixels and renders the page at 1:1 zoom on first load. The `content` attribute accepts a comma-separated list of directives: `width` (a pixel value or the keyword `device-width`), `height`, `initial-scale`, `minimum-scale`, `maximum-scale`, and `user-scalable`. Modern responsive design depends on this tag because CSS media queries and `device-width` units only behave as expected when the layout viewport equals the device width. The tag is not a CSS property and not a JavaScript API - it is static markup that the browser reads during initial parsing, so it must appear in the served HTML rather than being injected after render. Avoid disabling user scaling with `user-scalable=no` or `maximum-scale=1` because that breaks pinch-to-zoom, which many users with low vision rely on. Setting it correctly is foundational: every responsive layout, fluid grid, and mobile-first stylesheet assumes the viewport has been declared. It is one line, costs nothing at runtime, and its absence is one of the most common reasons a site looks broken on phones.",
    "aliases": [
        "viewport meta",
        "meta viewport",
        "device-width meta"
    ],
    "tags": [
        "mobile",
        "viewport",
        "responsive-design",
        "html-meta",
        "accessibility"
    ],
    "misconception": "Many developers think the viewport meta tag makes a site responsive on its own. It only configures the layout viewport - responsiveness still requires fluid CSS and media queries; the tag just lets those styles behave correctly.",
    "why_it_matters": "Omitting this tag makes mobile browsers render at desktop width and shrink the page, producing tiny unreadable text and horizontal scroll, while misusing it (disabling zoom) creates an accessibility failure for low-vision users.",
    "common_mistakes": [
        "Forgetting the tag entirely, so the browser falls back to a ~980px desktop viewport and shrinks the page.",
        "Setting `user-scalable=no` or `maximum-scale=1`, which disables pinch-to-zoom and fails WCAG zoom requirements.",
        "Using a fixed pixel `width` like `width=320` instead of `width=device-width`, breaking layout on other screen sizes.",
        "Injecting the tag via JavaScript after load instead of serving it in the initial HTML head.",
        "Placing the tag outside the document head where the browser may ignore it."
    ],
    "when_to_use": [
        "Any public-facing web page that should render correctly on phones and tablets.",
        "Whenever you rely on CSS media queries or mobile-first responsive styles that assume device-width sizing."
    ],
    "avoid_when": [
        "The document is a non-rendered fragment or email template where mobile browser viewport rules do not apply.",
        "You are building a desktop-only internal tool that will never be accessed on a mobile device and has fixed-width layout requirements."
    ],
    "related": [
        "responsive_design",
        "responsive_design_patterns",
        "meta_tags",
        "mobile_performance"
    ],
    "prerequisites": [
        "responsive_design"
    ],
    "refs": [
        "https://developer.mozilla.org/en-US/docs/Web/HTML/Viewport_meta_tag",
        "https://drafts.csswg.org/css-viewport/",
        "https://web.dev/articles/responsive-web-design-basics"
    ],
    "bad_code": "<!doctype html>\n<html>\n<head>\n  <title>My Site</title>\n  <!-- No viewport tag: mobile renders at ~980px and shrinks -->\n  <!-- Or worse, zoom disabled: -->\n  <meta name=\"viewport\" content=\"width=device-width, user-scalable=no, maximum-scale=1\">\n</head>\n<body>...</body>\n</html>",
    "good_code": "<!doctype html>\n<html>\n<head>\n  <title>My Site</title>\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n</head>\n<body>...</body>\n</html>",
    "quick_fix": "Add `<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">` to the document head and remove any `user-scalable=no` directive.",
    "severity": "medium",
    "effort": "low",
    "created": "2026-06-09",
    "updated": "2026-06-09",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/viewport_meta_tag",
        "html_url": "https://codeclaritylab.com/glossary/viewport_meta_tag",
        "json_url": "https://codeclaritylab.com/glossary/viewport_meta_tag.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Viewport Meta Tag](https://codeclaritylab.com/glossary/viewport_meta_tag) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/viewport_meta_tag"
            }
        }
    }
}