How to Emulate Mobile Viewports for Chrome Headless Website Screenshots

For a quick mobile-sized screenshot, set Chrome Headless’s window dimensions with --window-size:

chrome --headless --screenshot --window-size=412,892 https://example.com

This sets the screenshot window dimensions. It does not, by itself, emulate every mobile-device property. If the page depends on device pixel ratio, touch input, a mobile user agent, or mobile viewport behavior, configure device emulation through DevTools or ChromeDriver. The right setup depends on what you need to inspect.

1. Choose the kind of mobile screenshot you need

Start by deciding which behavior you want to reproduce:

Responsive layout at a chosen size: use Headless Chrome with --window-size=WIDTH,HEIGHT. This is suitable for checking CSS breakpoints and taking a quick narrow screenshot.
Mobile-specific rendering: configure a device profile or mobile emulation. This can include viewport characteristics, device pixel ratio, user agent, and touch behavior.
Hardware-dependent behavior: validate on a real mobile device. Desktop device emulation is an approximation, not execution on mobile hardware.

There is no universally correct mobile profile. Choose dimensions and device properties that match the question your screenshot is meant to answer.

2. Capture a mobile-sized screenshot with the Headless CLI

Use the Chrome executable available in your environment. The official Headless documentation demonstrates a 412 by 892 window:

chrome --headless --screenshot --window-size=412,892 https://example.com

Replace chrome with the executable name or full path for your installation if needed. The URL must be reachable from the machine running Chrome. The documented dimensions are an example configuration, not a specification for a particular phone.

Chrome’s documentation also shows a historical example using --window-size=412,732. Pick dimensions that fit your test case rather than treating either example as a standard device profile.

Check the output

Run the command and confirm Chrome exits successfully.
Open the generated screenshot and check the actual content area, responsive layout, and any scroll-dependent content.
If a breakpoint or asset selection behaves differently than expected, check the CSS viewport and whether the page depends on device pixel ratio or mobile-specific behavior.
If you need the whole page, determine whether your Chrome setup’s screenshot behavior captures only the visible viewport; use an automation workflow that explicitly supports full-page capture when necessary.

3. Understand viewport size, pixel ratio, and mobile behavior

A mobile screenshot can depend on more than its width and height. Keep these settings distinct when diagnosing a result:

Setting	What to check	When it matters
CSS viewport width and height	The layout dimensions the page uses	Responsive breakpoints, wrapping, and visible content
Device pixel ratio	Whether the emulated ratio matches the scenario	`window.devicePixelRatio`, resolution-sensitive CSS, and image selection
User agent and client hints	Whether the page serves mobile-specific content	User-agent detection or server-side variant selection
Touch behavior	Whether touch input is enabled for the emulated profile	Interfaces that change behavior for touch input
Mobile viewport characteristics	Whether mobile emulation is enabled in addition to setting dimensions	Pages whose rendering depends on mobile browser behavior
Capture extent	Viewport screenshot or full-page output	Whether content below the initial screen must appear in the image

Changing the window size is useful for layout checks, but it should not be treated as a substitute for configuring all the mobile properties your test requires.

4. Use device emulation when dimensions alone are not enough

Chrome DevTools Device Mode supports presets and custom CSS-pixel dimensions. Device profiles can configure properties such as resolution and pixel ratio, touch, and user agent. ChromeDriver also documents mobile emulation options for automated browser sessions.

Choose a device preset or define custom CSS viewport dimensions for the case you want to inspect.
Set device pixel ratio if resolution-sensitive CSS or image selection matters.
Enable the mobile behavior, user agent, client hints, and touch settings required by the page or test.
Capture the page and inspect whether the resulting viewport and assets match the intended scenario.

DevTools Device Mode is a first-order approximation of how a page looks and feels on mobile. It does not run the page on mobile hardware. If CPU architecture or another hardware-specific behavior matters, use Remote Debugging or test on a real device.

5. Avoid confusing a virtual screen with mobile emulation

Headless Chrome’s virtual screen settings control display properties such as origin, size, scale factor, orientation, and work area. A virtual display and mobile viewport emulation are separate capabilities. Setting a virtual screen alone does not establish that user agent, touch behavior, or other mobile emulation settings are configured.

Likewise, if you use Lighthouse with Puppeteer or another tool that already applies emulation, avoid applying a second, conflicting emulation configuration. Follow the configuration path for the tool that owns the browser session.

6. Common problems and fixes

Symptom	Likely cause	Fix
The screenshot has the requested narrow dimensions, but the page behaves like desktop	Only the window size was changed	Configure mobile emulation for the needed user agent, pixel ratio, touch, or mobile viewport behavior.
Images or resolution-sensitive styles differ from a phone	The emulated device pixel ratio differs from the target scenario	Set the intended pixel ratio in the emulation profile and capture again.
The server returns a desktop page	The site selects content using user agent or client hints	Configure the relevant mobile identity using the automation tool’s supported emulation settings; verify the server response as well as the screenshot.
Touch-dependent controls do not behave as expected	Touch behavior was not enabled or the test uses a mouse-only interaction	Enable touch emulation and use an interaction method appropriate to the test.
The screenshot omits content below the first screen	The capture is viewport-sized rather than full-page	Use a capture workflow that explicitly supports full-page screenshots, and check lazy-loaded content before capture.
The command cannot find Chrome	The executable is not on the shell’s PATH or has another name	Use the installed executable’s name or provide its full path.
The page is blank or incomplete	The page may not have finished loading, may require interaction, or may be inaccessible from the capture environment	Check that the URL is reachable, wait for the page’s required content in an automation workflow, and inspect browser output for load failures.
A Lighthouse result appears to use unexpected dimensions or identity	Emulation may have been applied both externally and by Lighthouse	Use one consistent emulation configuration path and remove duplicate settings.

7. Performance, reliability, and cost considerations

A CLI capture is a direct route for a small number of checks: it avoids setting up a browser automation script when dimensions alone answer the question. Device emulation adds configuration, but it is necessary when the page depends on mobile properties beyond size. Full-page captures and pages with substantial loading behavior can take longer than a simple viewport screenshot; wait for the content relevant to the result.

For repeatable comparisons, keep the viewport, pixel ratio, user agent, touch settings, capture extent, and page state consistent between runs. A screenshot from an emulated desktop browser is useful for visual inspection, but it cannot establish how hardware-specific behavior will perform on a phone. Use real-device validation when that distinction affects the result.

The CLI itself has no separate screenshot-service charge described here; operational costs depend on the machine and browser environment you run. A hosted screenshot API can avoid maintaining browser setup, with its own plan and request limits to consider.

8. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF; its API accepts the parameter names used by other screenshot APIs, which can make switching easier. See the ScreenshotNeo API documentation for its request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

These examples capture the target site through the API; use its viewport and device options when you need a particular mobile rendering. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account to get 1,000 screenshots a month without a card.

Frequently asked questions

Does `--window-size` make Chrome Headless a mobile browser?

No. It sets the window dimensions for the capture. Use device emulation when you also need mobile-specific properties such as pixel ratio, user agent, or touch behavior.

Are the example dimensions a particular phone’s specifications?

No. They are examples in Chrome documentation. Choose dimensions for the layout or scenario you need to inspect.

Can desktop emulation prove that a page works on a real phone?

No. Emulation approximates mobile behavior. Test on real hardware when the result depends on hardware-specific behavior.