Docs

Add the mobile viewport tag

Add the mobile viewport tag

Without the viewport tag, a phone assumes the page was built for a desktop screen. It lays the page out about 980 px wide and shrinks it to fit, so the text is tiny and visitors have to pinch and zoom to read anything. Your responsive CSS never kicks in, because as far as the browser knows, the screen is wide.

More than half of visits come from phones, and Google indexes the mobile version of a page first. The fix is one line in the page head. The site checklist marks it as a failure when the line is missing.

The tag

This line goes inside <head>, once, on every page:

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

width=device-width lays the page out at the phone's real width, initial-scale=1 opens it at normal size.

Do not disable zoom. Variants with user-scalable=no or maximum-scale=1 stop visitors from zooming in. People with low vision depend on it, accessibility guidelines (WCAG 1.4.4) require it, and Lighthouse flags it. Use exactly the line above.

Warning: If the site has no viewport tag because the theme or layout was never made responsive, adding the tag makes the page worse on phones: the desktop layout at phone width, with sideways scrolling. Look at the result on a phone right after the change. A non-responsive site needs a new theme or layout, not just this line.

Check it yourself

Replace example.com with your site:

curl -s https://example.com | grep -io '<meta[^>]*viewport[^>]*>'

Fixed means one line with width=device-width. Then open the page on a phone: the text should be readable without zooming.

How to fix

Pick how your site is built. Every current theme and builder adds the tag on its own, so a missing tag usually means an old theme or a hand-written layout.

WordPress

Every theme from the WordPress directory written in the last decade includes the tag. If yours does not, first consider whether the theme is responsive at all (see the warning above).

If it is, add the tag through wp_head with the free Code Snippets plugin (Snippets → Add New, run on the front end) or at the end of your child theme's functions.php. Do not put it in a parent theme: an update would overwrite it.

// Mobile viewport, for a theme that leaves it out.
add_action('wp_head', function () {
    echo '<meta name="viewport" content="width=device-width, initial-scale=1">' . "\n";
}, 1);

Check that the tag now appears once. If it shows up twice, the theme had it after all and the snippet is not needed. Then clear the page cache.

Node.js and Next.js

Next.js, App Router. Next.js adds the default tag width=device-width, initial-scale=1 to every page by itself. If it is missing, look for a custom viewport export or a hand-written <meta name="viewport"> in a layout that overrides it. To change the defaults, export viewport from a layout or page (Next.js 14 and newer), not a <meta> tag:

export const viewport = {
    width: 'device-width',
    initialScale: 1,
};

Next.js, Pages Router. Add the tag with next/head in pages/_app.js, not in pages/_document.js (Next.js warns against viewport tags there):

import Head from 'next/head';

export default function App({ Component, pageProps }) {
    return (
        <>
            <Head>
                <meta name="viewport" content="width=device-width, initial-scale=1" />
            </Head>
            <Component {...pageProps} />
        </>
    );
}

Other Node.js apps (Express with a template engine, Astro, SvelteKit): add the line to the <head> of the main layout. SvelteKit has it in src/app.html from the start.

Laravel

Add the line to <head> in every main layout, for example resources/views/layouts/app.blade.php and the separate guest or marketing layouts if you have them:

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

Layouts generated by Laravel's starter kits already include it.

Static HTML

Add the line inside <head> on every page, right after <meta charset="utf-8">:

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

With a site generator (Hugo, Jekyll, Eleventy), add it once to the base layout.

Shopify

Every theme from the Shopify Theme Store includes the tag. If yours is missing it, the theme was customised: open Online Store → Themes → … → Edit code, find layout/theme.liquid and add the line inside <head>:

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

Hosted builders

Wix, Squarespace and Webflow add the viewport tag to every page themselves, and you cannot remove it. If the checklist reports it missing on such a site, run the curl command above: the check may have reached a different page than you expect (for example a password page or a redirect to another host).

Confirm the fix

Run the curl command from Check it yourself again, then open the target in PulseKeeper and click Check now on the Checklist tab. The item turns OK within a few minutes instead of at the next daily run.