Viewport meta tag missing or incomplete

What Is This Issue

This issue checks whether your web pages have a properly configured <meta name="viewport"> tag in the HTML head section for mobile responsiveness.

A passing implementation includes a viewport meta tag with the following required directives:

width=device-width (matches the layout width to the device screen width)
initial-scale=1 (sets the initial zoom level to 1:1)

Example of correct implementation:


<meta name="viewport" content="width=device-width, initial-scale=1" />

Without this tag, mobile browsers render the page at a fixed desktop-equivalent width and scale it down, producing an unreadable zoomed-out layout. Google also uses this tag as a mobile-friendliness signal under mobile-first indexing.

Why Is This Important

The viewport meta tag is essential for mobile SEO and user experience:

Mobile-first indexing: Google uses mobile-friendliness as a ranking signal. Pages without a viewport tag may be considered mobile-unfriendly and rank lower in mobile search results.
User experience: Without proper viewport configuration, mobile users see a zoomed-out desktop version of the page, requiring them to pinch and zoom to read content.
Rankings: Mobile usability is a direct ranking factor. Pages that fail mobile-friendly tests may see decreased visibility in search results.
Crawlability: Google’s mobile crawler needs to properly render and understand mobile layouts to index them correctly.

Resolving this issue improves your SEO health score by ensuring your pages are mobile-friendly, which is critical since Google primarily uses the mobile version of content for indexing and ranking.

How XeoPix Detects This

XeoPix performs the following checks to detect this issue:

HTML parsing: The crawler extracts the <head> section from the page’s HTML content.
Meta tag search: It looks for a <meta> tag with the attribute name="viewport" (case-insensitive).
Content validation: If the tag is found, XeoPix checks the content attribute for the presence of:
- width=device-width directive
- initial-scale=1 directive
Duplicate detection: The crawler counts all viewport meta tags in the head section and flags if more than one exists.
Pass/Fail determination:
- Passes: If a viewport meta tag exists with both width=device-width and initial-scale=1 in the content attribute
- Fails: If the viewport meta tag is missing, or if it’s missing either required directive

The detection focuses on whether the tag exists and contains the essential directives for mobile responsiveness, not on optional parameters like shrink-to-fit or viewport-fit.

How To Fix

Follow these steps to implement the viewport meta tag correctly:

Add the viewport meta tag to your HTML head: Place the following line inside the <head> section of your HTML document:
```
<meta name="viewport" content="width=device-width, initial-scale=1" />
```
Ensure correct placement: The viewport meta tag should be placed early in the <head> section, before any CSS or JavaScript that might affect layout.
Verify the content attribute: Ensure the content attribute includes:
- width=device-width (required)
- initial-scale=1 (recommended)
Remove duplicate tags: If multiple viewport meta tags exist, consolidate them into a single tag with the correct content value.
Verify implementation:
- Use Google’s Mobile-Friendly Test tool to confirm the page passes
- Use browser developer tools to test the page on various device sizes
- Check that text and elements are readable without zooming

Note: Avoid adding user-scalable=no or maximum-scale restrictions, as these prevent users from zooming and may negatively impact accessibility.

What We Store

Storage Level

Page Level — This issue is evaluated for each individual URL.

Database Table / Prisma Model

PageHtmlHeadAudit

Stored Fields

Field	Type	Description
viewportContent	String?	The content attribute of the viewport meta tag

Detection Dependencies

The following data sources are required to evaluate this issue:
HTML Document — The crawler parses the HTML head section to find the viewport meta tag
Meta Tag Extraction — The <meta name="viewport"> tag is extracted

Examples

Example 1: Correct Implementation

Scenario: A properly configured page with viewport meta tag.

Correct State (Passes):


<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Page Title</title>
</head>

Example 2: Missing Viewport Meta Tag

Scenario: Page has no viewport meta tag.

Problematic State (Fails):


<head>
  <meta charset="UTF-8" />
  <title>Page Title</title>
  <link rel="stylesheet" href="styles.css" />
</head>

Why it fails: Mobile browsers will render the page at a fixed desktop width and scale it down, making content unreadable on mobile devices.

Corrected State (Passes):


<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Page Title</title>
  <link rel="stylesheet" href="styles.css" />
</head>

Example 3: Incomplete Viewport Meta Tag

Scenario: Viewport meta tag is present but missing required directives.

Problematic State (Fails):


<head>
  <meta name="viewport" content="width=device-width" />
  <title>Page Title</title>
</head>

Why it fails: Missing initial-scale=1 directive, which may cause some browsers to apply a non-standard zoom factor on initial load.

Corrected State (Passes):


<head>
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Page Title</title>
</head>

Example 4: Fixed Width Instead of Device-Width

Scenario: Viewport uses fixed pixel width instead of device-width.

Problematic State (Fails):


<head>
  <meta name="viewport" content="width=1024" />
  <title>Page Title</title>
</head>

Why it fails: Using a fixed width (e.g., 1024) instead of width=device-width causes the layout to ignore the device screen width, breaking mobile responsiveness.

Corrected State (Passes):


<head>
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Page Title</title>
</head>

Example 5: Duplicate Viewport Meta Tags

Scenario: Multiple viewport meta tags present in the head.

Problematic State (Fails):


<head>
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <meta name="viewport" content="width=device-width" />
  <title>Page Title</title>
</head>

Why it fails: Multiple viewport meta tags can cause browsers to apply the last one encountered, which may differ from the intended configuration.

Corrected State (Passes):


<head>
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Page Title</title>
</head>

Unit Test

Test File

__tests__/seo-audit-checks/htmlHeadTags/issue-104-meta-name-viewport.test.js

Purpose

Validates the detection of missing or incomplete <meta name="viewport"> declarations in the HTML <head>. Ensures pages are flagged when the viewport tag is missing or lacks required directives (width=device-width and initial-scale=1).

Tested Function

runHtmlHeadTags() from toggleGroups/htmlHeadTags.js

Issue Information

Issue Number: 104
Issue Code: META_NAME_VIEWPORT
Toggle Group: htmlHeadTags

Test Scenarios

Positive Test Cases

Page has <meta name="viewport" content="width=device-width, initial-scale=1"> — no issue reported
Page has <meta name="viewport" content="width=device-width, initial-scale=1.0"> — no issue reported
Viewport directives with extra whitespace — no issue reported
Case-insensitive directive names (WIDTH=DEVICE-WIDTH, INITIAL-SCALE=1) — no issue reported

Negative Test Cases

Page has no viewport meta tag — issue reported with message "Viewport metadata is missing"
Viewport is missing width=device-width directive — issue reported with missing containing "width=device-width"
Viewport is missing initial-scale=1 directive — issue reported with missing containing "initial-scale=1"
Viewport is missing both required directives — issue reported with both in missing

Boundary Cases

None present.

Edge Cases

Empty HTML (<html></html>): issue reported (viewport metadata is missing)
Whitespace handling: directives with extra surrounding whitespace are correctly parsed
Case-insensitivity: directive names are matched case-insensitively

Expected Outcome

Pass

The issue should be reported when:

The viewport meta tag is completely absent
The viewport tag exists but is missing width=device-width
The viewport tag exists but is missing initial-scale=1
The viewport tag exists but is missing both required directives

Fail

The issue should not be reported when:

Both width=device-width and initial-scale=1 are present (any order, any case)
initial-scale=1.0 is used (equivalent to initial-scale=1)
Directives contain extra whitespace

Validation

Correct detection of missing viewport meta tag
Correct identification of missing required directives
Whitespace-tolerant directive parsing
Case-insensitive directive name matching
Cache mechanism prevents duplicate issue entries on repeated calls

toggleGroups/htmlHeadTags.js
issueCodes.js

Coverage Summary

Positive cases: 4 (both directives, initial-scale=1.0, whitespace, case-insensitive)
Negative cases: 4 (missing tag, missing width, missing initial-scale, missing both)
Edge cases: 2 (empty HTML, whitespace, case-insensitivity)
Cache validation: 1

References

Mobile-first indexing — Google Search Central
Viewport meta tag — MDN
Mobile-friendly test — Google Search Central

Viewport meta tag missing or incomplete

What Is This Issue

Why Is This Important

How XeoPix Detects This

How To Fix

What We Store

Storage Level

Database Table / Prisma Model

Stored Fields

Detection Dependencies

Examples

Example 1: Correct Implementation

Example 2: Missing Viewport Meta Tag

Example 3: Incomplete Viewport Meta Tag

Example 4: Fixed Width Instead of Device-Width

Example 5: Duplicate Viewport Meta Tags

Unit Test

Test File

Purpose

Tested Function

Issue Information

Test Scenarios

Positive Test Cases

Negative Test Cases

Boundary Cases

Edge Cases

Expected Outcome

Pass

Fail

Validation

Related Production Files

Coverage Summary

References