If a Puppeteer screenshot shows a desktop layout, set the intended viewport—or emulate a device—before navigating, then check the page’s actual viewport and the screenshot options. A successful call to page.viewport() confirms Puppeteer’s configured setting; it does not prove what the page rendered.
Set the mobile viewport before navigating
For a layout test that needs a particular CSS viewport size, call page.setViewport() before page.goto(). The dimensions below are an example, not a universal phone standard:
As an Amazon Associate I earn from qualifying purchases.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
await page.setViewport({
width: 390,
height: 844,
deviceScaleFactor: 1,
});
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'mobile.png' });
await browser.close();Puppeteer advises setting the viewport before navigation because some websites do not expect a phone-sized window to change after loading. Changing mobile or touch properties can reload a page in some cases. See Puppeteer’s Page.setViewport() documentation. The screenshot guide’s use of networkidle2 is an example wait condition, not a guarantee that every site is ready at that event; choose a wait condition or application-specific readiness check that fits the page. See the Puppeteer screenshots guide.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsChoose dimensions or a device profile
| Approach | Use it when | What it configures | Important consideration |
|---|---|---|---|
page.setViewport() |
You need a particular width and height for a CSS layout test. | Viewport dimensions and optional properties such as device scale factor. | It does not by itself set a mobile user agent. Set it before navigation for predictable mobile-layout behavior. Source |
page.emulate(device) |
You want a named device profile rather than dimensions alone. | A user agent and viewport together. | Emulate before navigation. Device definitions can change between Puppeteer releases. Source |
Emulate a known device
Use KnownDevices when your test needs Puppeteer’s bundled user agent and viewport values for a device. For example:
#1 Best Overall
- YOUR CONTENT, SUPER SMOOTH: The ultra-clear 6.7" FHD+ Super AMOLED display of Galaxy A17 5G helps bring your content to life, whether you're scrolling through recipes or video chatting with loved ones.¹
- LIVE FAST. CHARGE FASTER: Focus more on the moment and less on your battery percentage with Galaxy A17 5G. Super Fast Charging powers up your battery so you can get back to life sooner.²
- MEMORIES MADE PICTURE PERFECT: Capture every angle in stunning clarity, from wide family photos to close-ups of friends, with the triple-lens camera on Galaxy A17 5G.
- NEED MORE STORAGE? WE HAVE YOU COVERED: With an improved 2TB of expandable storage, Galaxy A17 5G makes it easy to keep cherished photos, videos and important files readily accessible whenever you need them.³
- BUILT TO LAST: With an improved IP54 rating, Galaxy A17 5G is even more durable than before.⁴ It’s built to resist splashes and dust and comes with a stronger yet slimmer Gorilla Glass Victus front and Glass Fiber Reinforced Polymer back.
import puppeteer, { KnownDevices } from 'puppeteer';
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
await page.emulate(KnownDevices['iPhone 17 Pro']);
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'iphone.png' });
await browser.close();Use a device name available in the Puppeteer version installed in your project; profiles are version-dependent. See Page.emulate() for the API and Page.setViewport() for the distinction between sizing and mobile-related properties.
Verify what Puppeteer configured and what the page sees
Log the configured viewport, then inspect dimensions from inside the page. These checks answer different questions: page.viewport() returns Puppeteer’s configured settings, while window.innerWidth and document.documentElement.clientWidth provide in-page measurements.
Rank #2
- Carrier: This phone is locked to Tracfone, which means this device can only be used on the Tracfone wireless network. Tracfone plan required, activating is easy, just 3 steps.
- DISPLAY: Immersive viewing on a 6.7-inch super-bright 120Hz display with powerful stereo speakers and Bass Boost for cinematic entertainment.
- CAMERA SYSTEM: Advanced 50MP Quad Pixel camera captures sharp, detailed photos and videos in any lighting condition
- PERFORMANCE: Lightning-fast 5G connectivity paired with a powerful processor and RAM Boost for smooth multitasking.
- BATTERY LIFE: Long-lasting 5000mAh battery with TurboPower charging technology delivers hours of power in minutes.
console.log('Puppeteer configuration:', page.viewport());
const measurements = await page.evaluate(() => ({
innerWidth: window.innerWidth,
clientWidth: document.documentElement.clientWidth,
innerHeight: window.innerHeight,
}));
console.log('Page measurements:', measurements);Do not treat a matching page.viewport() value as proof that the site used the expected mobile layout. The API documentation explicitly notes that this accessor does not check the actual page viewport. Compare its result with in-page measurements and inspect the page’s rendered state. See Page.viewport().
Recommended Free Tools
Make sure screenshot options are not changing the captured region
A correct viewport does not necessarily mean the screenshot is limited to the visible viewport. Review fullPage, clip, and captureBeyondViewport:
Rank #3
- YOUR CONTENT, SUPER SMOOTH: The ultra-clear 6.7" FHD+ Super AMOLED display of Galaxy A17 5G helps bring your content to life, whether you're scrolling through recipes or video chatting with loved ones.¹
- LIVE FAST. CHARGE FASTER: Focus more on the moment and less on your battery percentage with Galaxy A17 5G. Super Fast Charging powers up your battery so you can get back to life sooner.²
- MEMORIES MADE PICTURE PERFECT: Capture every angle in stunning clarity, from wide family photos to close-ups of friends, with the triple-lens camera on Galaxy A17 5G.
- NEED MORE STORAGE? WE HAVE YOU COVERED: With an improved 2TB of expandable storage, Galaxy A17 5G makes it easy to keep cherished photos, videos and important files readily accessible whenever you need them.³
- BUILT TO LAST: With an improved IP54 rating, Galaxy A17 5G is even more durable than before.⁴ It’s built to resist splashes and dust and comes with a stronger yet slimmer Gorilla Glass Victus front and Glass Fiber Reinforced Polymer back.
fullPage: truerequests a capture of the full page rather than only the visible viewport.clipspecifies a rectangular area to capture. Check its coordinates and dimensions against the result you expect.captureBeyondViewportdefaults tofalsewhen no clip is supplied andtruewhen a clip is supplied.
For a straightforward viewport-sized image, omit full-page and clip settings unless you need them. The exact behavior and other screenshot settings are documented in Puppeteer’s ScreenshotOptions API.
Check defaults when connecting to a browser
If your script uses puppeteer.connect(), inspect its defaultViewport setting as well as any later calls that resize the page. Puppeteer documents a default ConnectOptions.defaultViewport of 800×600. A connection-level default can therefore explain a desktop-sized capture if the script never overrides it. See ConnectOptions.
Rank #4
- PRIVACY DISPLAY: Automatically hide your screen from those beside you. The built-in privacy display can be preset¹ to turn on when receiving notifications, typing passwords, or using specific apps
- TYPE IT IN. TRANSFORM IT FAST: Enhance any shot in seconds on your smartphone by using Photo Assist² with Galaxy AI.³ Add objects, restore details, or apply new styles by simply typing or tapping
- NIGHTS, CAPTURED CLEARLY: From gigs to city lights, record and capture moments after dark with clarity using Nightography so your photos and videos stay crisp and clear on your Samsung Galaxy
- MAKE IT. EDIT IT. SHARE IT: Turn everyday moments into something personal with creative tools built right into your mobile phone, whether it’s a special contact photo, custom wallpaper, an invitation or more⁴
- HELP THAT KEEPS UP: Stay in the moment while Now Nudge with Galaxy AI helps you respond faster and stay organized with smart suggestions⁵ that appear exactly when you need them on your phone
Page viewport and browser screen are related but distinct. Puppeteer’s screen-configuration guide says headless mode has one 800×600 screen when neither --screen-info nor --window-size is used. Changing a page viewport is not the same as configuring the browser window or screen. See Screen configuration and Window management. The latter demonstrates resizing content with Page.resize() and removing the default viewport with page.setViewport(null) in its window-management example; use those techniques when you specifically need to manage the browser window rather than a fixed page viewport.
Troubleshoot the common causes
| Symptom | What to check | Next step |
|---|---|---|
| The screenshot uses desktop styling. | Was the viewport set before navigation? Does the test need a mobile user agent or device metrics as well as a narrow width? | Set dimensions before goto(), or emulate a known device before navigation. |
page.viewport() reports the expected width, but the layout still looks wrong. |
That method reports configured settings, not the actual page viewport. | Measure window.innerWidth and document.documentElement.clientWidth in the page, then inspect the rendered layout and runtime configuration. |
| The image shows the whole long page or an unexpected rectangle. | Check fullPage, clip, and captureBeyondViewport. |
Remove full-page or clip options for a normal viewport capture, or correct the clip dimensions. |
| A connected browser unexpectedly uses 800×600. | Check puppeteer.connect() and whether a later call overwrites the intended viewport. |
Set the desired viewport explicitly and review the connection’s defaultViewport. |
| The page changes after viewport setup or does not settle when captured. | Some mobile or touch setting changes can reload a page; a generic lifecycle wait may not mean the application is ready. | Configure before navigation and wait for the selector, state, or content your application actually needs before capturing. |
These checks narrow down Puppeteer configuration and capture-region problems. They cannot establish the cause of every site-specific failure: application CSS, viewport metadata, scripts that run after navigation, browser version, and custom connection setup can also affect the result.
Best Value
- Carrier: This phone is locked to Tracfone, which means this device can only be used on the Tracfone wireless network. Activating is easy, just 3 steps.
- ACTIVATION Promotion: Includes 1500 min, 1500 texts & 1500 MB Data + add more as you need it
- CAMERA SYSTEM: 50MP Quad Pixel camera. Capture sharper, more vibrant photos day or night with 4x the light sensitivity.
- PERFORMANCE: Blazing-fast Qualcomm performance. Get the speed you need for great entertainment with a Snapdragon 680 processor and 4GB of RAM.
- 64GB built-in storage. Get plenty of room for photos, movies, songs, and apps. Made for US
Or skip the browser setup
If you need a screenshot through an API rather than configuring Puppeteer, ScreenshotNeo returns an image or PDF from one GET request. Example cURL request (see the ScreenshotNeo documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo accepts cookie or consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, with the result identified by response headers. Its MCP server gives AI agents screenshot, page-info, and PDF-capture tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for the free plan.
Frequently Asked Questions
Does setting a narrow viewport automatically use a mobile user agent?
No. page.setViewport() sets viewport dimensions and optional properties; use page.emulate() when you need a bundled device user agent and viewport.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Does networkidle2 guarantee that a page is ready for a screenshot?
No. It is a documented example wait condition, not a universal signal that every application has finished rendering the state you want.
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.
