Recommended Free Tools
Set a Puppeteer page’s viewport with await page.setViewport({ width, height }), and do it before navigating when possible. For example, await page.setViewport({ width: 640, height: 480 }) sets a 640-by-480 viewport. The viewport belongs to the page; it is not the same as resizing the browser window.
Set the viewport before navigating
Create a page, await setViewport(), then navigate. The Puppeteer API returns a Promise<void>, so awaiting it ensures the viewport call finishes before the next operation.
As an Amazon Associate I earn from qualifying purchases.
const page = await browser.newPage();
await page.setViewport({
width: 640,
height: 480,
deviceScaleFactor: 1,
});
await page.goto('https://example.com');The deviceScaleFactor field is included in Puppeteer’s official example; the values shown here are examples, not required dimensions. See the Page.setViewport() reference and the Getting started guide.
Choose dimensions for the layout you need
Pass the width and height you want in the viewport object. Puppeteer’s Getting Started guide also demonstrates a viewport of 1080 by 1024. These are configuration examples, not measurements or recommended universal sizes. The full set of supported viewport properties and defaults can depend on your installed Puppeteer version, so consult that version’s API reference rather than assuming the example is exhaustive.
#1 Best Overall
Why set it before navigation?
Puppeteer recommends setting the viewport before navigating because some sites do not expect phones to change size. In certain cases, changing isMobile or hasTouch can cause a page reload. Set the desired viewport first when you want a page to load directly at the intended dimensions.
Choose the right Puppeteer sizing method
These APIs affect different things. Use the one that matches what you need to control.
Rank #2
| Method or option | What it controls | Use it when |
|---|---|---|
page.setViewport(viewport) |
The page viewport and related viewport settings. | You need a page to render at chosen viewport dimensions. |
page.emulate(device) |
Device metrics and user agent, including viewport setup. | You want a documented device profile rather than dimensions alone. |
page.resize({ contentWidth, contentHeight }) |
Browser-window content dimensions in the window-management workflow. | You specifically need to resize browser-window content, not just set a page viewport. |
ConnectOptions.defaultViewport |
A default viewport applied to each page through connection options. | You want a default configured when connecting. |
See Puppeteer’s viewport reference, emulate reference, window management guide and ConnectOptions reference.
Set a default viewport for pages
page.setViewport() changes a particular page. Separately, ConnectOptions.defaultViewport configures a default viewport for each page. The Puppeteer reference shows an 800-by-600 example. Use this connection-level option when you want a shared default; call setViewport() when you need to configure a page directly.
Emulate a mobile device
If you need both device metrics and a matching user agent, use page.emulate(device) rather than manually setting only width and height. Puppeteer documents it as a shortcut for Page.setUserAgent() plus Page.setViewport() and recommends emulating before navigation.
const { KnownDevices } = require('puppeteer');
const iPhone = KnownDevices['iPhone 13'];
const page = await browser.newPage();
await page.emulate(iPhone);
await page.goto('https://example.com');Choose a device profile available in the KnownDevices collection for your installed Puppeteer version. See the Page.emulate() reference for the documented device-emulation method.
Reset a page viewport
Pass null to reset a page’s viewport to its default:
await page.setViewport(null);This page-level reset is distinct from choosing a viewport through connection options.
Best Value
- Used Book in Good Condition
Resize browser-window content instead
If the target is browser-window content sizing rather than the page viewport, follow Puppeteer’s window-management workflow: remove the default viewport, then call page.resize().
await page.setViewport(null);
await page.resize({ contentWidth: 600, contentHeight: 400 });The documented inner-window size change is asynchronous. If you need to read the resulting dimensions, wait for the resize event before measuring, as shown in the window management guide.
Troubleshooting viewport issues
- The page uses unexpected dimensions: Confirm you awaited
page.setViewport()and called it beforepage.goto(). Check that you changed the intended page; Puppeteer pages can have independent viewports. - The page reloads after a viewport change: A reload can occur in certain cases when changing
isMobileorhasTouch. Set those options as part of the initial viewport configuration before navigation where practical. - The browser window did not resize as expected:
setViewport()sets the page viewport, not browser-window content dimensions. Use the documentedpage.setViewport(null)andpage.resize()workflow for the latter. - A device profile or option is unavailable: Puppeteer APIs and device profiles are version-sensitive. Check the reference for the version installed in your project, and do not assume the example fields cover every supported option.
Or skip the browser setup
If you need a screenshot rather than a Puppeteer workflow, ScreenshotNeo provides a website screenshot API and MCP server. A single GET request returns a PNG, JPEG, WebP or PDF. Its API supports viewport and device presets along with other capture options; 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/consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server lets AI agents—including Claude, Cursor and other MCP clients—use screenshot tools. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
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.
