To capture a page with mobile browser settings in Puppeteer, apply a device descriptor with await page.emulate(device) before navigating, then capture it with page.screenshot(). If you need a custom setup, set the viewport, device scale factor, mobile behavior and touch support separately. These settings emulate browser-facing conditions; they do not establish that the result matches every behavior of a physical phone.
Emulate the device before loading the page
A mobile screenshot depends on more than making a desktop window narrower. A page’s layout can respond to its viewport, the device scale factor, mobile viewport behavior and user-agent string. Touch support may also matter to pages that respond differently to touch input. Puppeteer’s page.emulate(device) applies a device descriptor’s metrics and user agent; it is a shortcut for setting the user agent and viewport. The official Puppeteer Page API documents KnownDevices for use with Page.emulate().
Set emulation before page.goto(). A page that first loads as desktop and is resized afterwards may not behave as though it was opened on a phone. Puppeteer notes that some sites do not expect a phone-sized resize after navigation, and changing mobile or touch settings can reload the page.
- Create a browser page.
- Choose a device descriptor available in the Puppeteer version installed in your project, or define the needed viewport settings yourself.
- Apply emulation before navigating.
- Navigate and wait for the page state you actually want to capture.
- Call
page.screenshot()with the appropriate capture options.
Complete example using a known-device descriptor
This ES module example uses the iPhone 13 descriptor shown in Puppeteer’s device collection. Device names can vary by installed release, so verify that this key exists in your local KnownDevices collection rather than assuming every version includes it. The documentation search surfaced Puppeteer API references at version 25.12.0; check your project’s installed version because API fields and descriptors can change.
#1 Best Overall
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
const device = puppeteer.KnownDevices['iPhone 13'];
if (!device) {
throw new Error('The iPhone 13 descriptor is not available in this Puppeteer version.');
}
await page.emulate(device);
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'mobile.png', fullPage: true });
} finally {
await browser.close();
}The official screenshot guide demonstrates navigation with networkidle2 before capturing. Treat that as a useful wait condition, not a guarantee that every image, animation, lazy-loaded section or application-specific state is ready. For pages with important dynamic content, choose a wait strategy based on that page’s behavior and confirm the intended content is present before taking the screenshot.
Configure a custom mobile viewport
Use separate viewport settings when the target dimensions or behavior do not match an available descriptor, or when you want to vary one setting at a time. Viewport width and height are measured in CSS pixels, not necessarily the number of raster pixels in the resulting image. The Puppeteer Viewport reference describes the relevant fields and their defaults.
await page.setViewport({
width: 390,
height: 844,
deviceScaleFactor: 2,
isMobile: true,
hasTouch: true,
});
await page.setUserAgent('YOUR_MOBILE_USER_AGENT');
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'custom-mobile.png' });Replace YOUR_MOBILE_USER_AGENT with the user-agent string appropriate to the test. The values above are illustrative custom settings, not a claim that they represent a specific phone. If you only need responsive layout at a particular CSS width, you may not need to change the user agent or enable touch. If the site branches on those signals, configure and verify them explicitly.
Rank #2
| Setting | What it changes | When to use it |
|---|---|---|
width, height |
Viewport dimensions in CSS pixels. | To exercise a responsive breakpoint or match a target viewport. |
deviceScaleFactor |
Device scale factor; the documented default is 1. | To test higher-density rendering separately from CSS layout size. |
isMobile |
Whether the page’s meta viewport tag is taken into account; the documented default is false. | To test mobile viewport behavior rather than only a narrow desktop viewport. |
hasTouch |
Whether the viewport supports touch events; the documented default is false. | When page behavior depends on touch support. |
| User agent | The user-agent value sent by the emulated browser. | When the target varies its response based on that browser-facing value. |
With a known descriptor, page.emulate(device) sets the descriptor’s device metrics and user agent together. With manual settings, be deliberate about which values you change: viewport size, device scale, mobile viewport handling, touch support and user agent are related test inputs, not interchangeable ways to say “phone.”
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Choose viewport, full-page or element capture
By default, page.screenshot() captures the current viewport. For a tall page, fullPage: true requests a full-page screenshot. Use clip when you need a specific rectangle instead of the whole viewport or document. A clip and a full-page capture answer different questions: one isolates a region, while the other captures the document’s full page height. Puppeteer’s ScreenshotOptions reference documents these options.
// Viewport screenshot
await page.screenshot({ path: 'viewport.png' });
// Full document screenshot
await page.screenshot({ path: 'full-page.png', fullPage: true });
// Region screenshot
await page.screenshot({
path: 'region.png',
clip: { x: 0, y: 0, width: 390, height: 500 },
});To capture a component rather than the page, locate it and use ElementHandle.screenshot(). Puppeteer’s screenshot guide says it attempts to scroll a hidden element into view before capturing it. This is useful for component checks, but it does not replace a full-page screenshot when you need to inspect overall layout.
typeselects output format; the documented default is PNG.qualityaccepts a value from 0 to 100 for supported lossy formats and does not apply to PNG.omitBackground: truehides the default white background for transparent output.pathwrites the screenshot to a file; use a path that is writable by the process running Puppeteer.
For a full-page mobile capture, check both its width and its total height: the height can exceed the configured viewport because the whole document is requested. For a clipped capture, ensure the region is the one you intend to compare; a clip outside the visible viewport may require the relevant capture settings documented by Puppeteer.
What emulation can and cannot tell you
Puppeteer’s documented settings reproduce browser-facing metrics and user-agent behavior, including viewport dimensions, device scale, mobile viewport handling and touch support. That makes emulation useful for repeatable responsive-layout screenshots and for checking code paths that depend on those inputs.
It is not proof of complete physical-device fidelity. The cited API documentation describes browser configuration; it does not promise that every hardware-specific phone behavior is reproduced. If a defect depends on a particular handset, operating system, browser implementation or physical input, treat an emulated screenshot as one test rather than a substitute for validating the real target environment.
Troubleshooting mobile screenshots
The page still looks like desktop
- Confirm that
page.emulate()or the custom viewport call runs beforepage.goto(). - Check the descriptor exists in the installed Puppeteer version and that the code is applying it to the page being captured.
- If you configure settings manually, verify the CSS-pixel width and whether
isMobileshould be enabled for the page’s meta viewport behavior.
The screenshot has the wrong dimensions
- Distinguish CSS viewport dimensions from device scale factor; they control different aspects of rendering.
- Check whether you asked for a viewport image, full-page image or clipped region. A full-page capture can be taller than the viewport.
- Check the output type and quality options if you are comparing files rather than page layout.
Content is missing or appears in the wrong state
networkidle2is an example wait condition, not a promise that every lazy image or animation has completed.- Wait for the relevant content or application state before capture, and inspect whether the page requires interaction to reveal it.
- For an element screenshot, verify that the selected element is the intended one; Puppeteer may scroll it into view before capturing.
Changing settings reloads or disrupts the page
Apply viewport and device configuration before navigation wherever possible. Puppeteer warns that changing mobile or touch settings may reload a page, while resizing after navigation can be unexpected for some sites. If you need to compare configurations, create a fresh page for each configuration and navigate only after applying it.
A device name is undefined
Check the exact key available in the installed KnownDevices collection. A name present in an example or in another Puppeteer release is not guaranteed to be in yours; use the available descriptor or configure the viewport manually.
Performance, repeatability and cost
For stable comparisons, keep the test inputs fixed: descriptor or viewport values, user agent when customized, URL, wait condition and screenshot options. A screenshot taken at a different page state is not a reliable layout comparison even if the viewport is identical. Record the installed Puppeteer version with the test setup, since the device collection and API details are version-sensitive.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallBest Value
- Used Book in Good Condition
The cited Puppeteer references do not publish performance benchmarks or a cost schedule. In a local workflow, the practical constraints are the browser process and the time your page takes to reach a capturable state. Avoid waiting longer than the page requires, but do not trade away the state your screenshot is meant to test. For repeatable runs, close the browser in a finally block as in the example, so errors during navigation or capture do not leave that process open.
Or skip the browser setup
If you need an API call rather than maintaining a local Puppeteer browser, ScreenshotNeo is a website screenshot API and MCP server. This one-call Node.js example requests an image for a URL; consult the ScreenshotNeo documentation for API options, including device and viewport configuration.
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info and capture_pdf for AI agents and MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan to start with 1,000 screenshots a month and no card.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Frequently Asked Questions
Does a Puppeteer mobile screenshot test a real mobile browser?
No. Puppeteer emulation configures browser-facing metrics and user-agent behavior, but the cited documentation does not claim complete fidelity to a physical phone or every mobile browser.
Can I compare several phone-sized layouts in one test suite?
Yes. Create a page for each available device descriptor or custom viewport configuration, apply its settings before navigation, and keep the target page state and capture options consistent.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
