How to fix mobile viewport on Headless / Custom (I build in code)

Steps for Headless / Custom (I build in code)

1. Locate the root HTML shell or document component — e.g. `pages/_document.tsx` in Next.js, `app.html` in SvelteKit, `index.html` in a Vite/CRA app, or the root layout file in your framework.
2. Add `<meta name="viewport" content="width=device-width, initial-scale=1">` inside the `<head>` element.
3. In Next.js App Router, use the Metadata API instead: export a metadata object with `{ viewport: { width: 'device-width', initialScale: 1 } }` from your root layout.
4. In Nuxt 3, set `viewport` inside `useHead()` or in `nuxt.config.ts` under `app.head.meta`.
5. Redeploy and verify with `curl -s <your-url> | grep viewport` or Chrome DevTools.

What is mobile viewport?

The viewport meta tag is a single line of HTML code placed in the `<head>` of every page. It tells mobile browsers (phones, tablets) how wide to display your site and whether to let visitors pinch-to-zoom. Without it, mobile browsers assume your site is a full desktop page — usually 980px wide — and shrink everything down to fit the screen, making text tiny and buttons nearly impossible to tap. Adding `<meta name="viewport" content="width=device-width, initial-scale=1">` tells the browser to match the device's actual screen width and show your content at a normal, readable size.

Google uses mobile-first indexing, meaning it primarily crawls and ranks your site based on its mobile version. A missing or broken viewport tag signals to Google that your site is not mobile-friendly, which directly suppresses your rankings in search results — especially for the majority of shoppers who search on their phones. Beyond rankings, a site that renders incorrectly on mobile produces a poor user experience: visitors can't read product descriptions, miss calls-to-action, and abandon their carts. Google's own PageSpeed and Core Web Vitals scoring also penalises pages that fail basic mobile usability checks, compounding the ranking impact.

See the complete Mobile viewport guide for every platform and the full background.