Recommended Free Tools
Puppeteer’s screenshot API is built into its browser automation library: use page.screenshot() to capture a page, and elementHandle.screenshot() to capture one DOM element. You can save the result to a file, keep the image bytes in memory, or request base64 text. This guide shows the complete Node.js workflow, explains the options that affect capture scope and output, and covers common failure cases.
Which Puppeteer screenshot method should you use?
| Need | Method or option | What it captures |
|---|---|---|
| Visible page | page.screenshot() |
The page’s screenshot, normally the current viewport. |
| Entire document | page.screenshot({ fullPage: true }) |
A full-page image rather than just the visible viewport. |
| Specific rectangular region | page.screenshot({ clip: { x, y, width, height } }) |
The region specified by the clip coordinates and dimensions. |
| One DOM element | elementHandle.screenshot() |
The selected element; Puppeteer scrolls it into view if needed. |
The official Puppeteer guide recommends Page.screenshot() for page captures: Puppeteer Screenshots guide. Use an element handle instead of a page clip when the target is a particular DOM node and its current rendered bounds are what matter.
Install Puppeteer and take a basic screenshot
The following is a complete Node.js script using Puppeteer’s documented launch, navigation, capture, and close sequence. It writes a PNG file. The guide demonstrates waitUntil: 'networkidle2'; treat that as an example readiness condition, not a guarantee that all dynamic content on every site has finished rendering.
-
Create a project and install Puppeteer with
npm install puppeteer. Puppeteer downloads a compatible browser during installation unless your setup is configured differently.Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Save this as
screenshot.mjs:import puppeteer from 'puppeteer'; const browser = await puppeteer.launch(); try { const page = await browser.newPage(); await page.goto('https://news.ycombinator.com', { waitUntil: 'networkidle2', }); await page.screenshot({ path: 'hn.png' }); } finally { await browser.close(); } -
Run it with
node screenshot.mjs. The output file,hn.png, is created in the current working directory.
The try/finally block ensures the browser is closed even if navigation or screenshot capture throws an error. In a long-running application, consider reusing a browser process across jobs rather than launching one for every image, while creating an appropriately isolated page for each capture.
Save the image, return bytes, or use base64
Puppeteer returns binary image data as a Uint8Array by default. Set path when you want Puppeteer to write the image to disk; the output format is inferred from the file extension. With no path, Puppeteer does not save an image file.
const imageBytes = await page.screenshot();
// imageBytes is a Uint8Array; pass it to code that accepts binary image data.If another system specifically requires base64-encoded text, request it explicitly:
const base64Image = await page.screenshot({ encoding: 'base64' });Base64 is text representing the image bytes, not a different capture mode. It is useful for interfaces that accept data URLs or text payloads, but binary data is generally the more direct form for writing or uploading an image. Avoid converting a large screenshot to base64 unless the receiving interface needs it.
Capture a full page, a region, or a DOM element
Full-page capture
Set fullPage: true to capture the full page rather than only the viewport:
Rank #2
await page.screenshot({ path: 'full-page.png', fullPage: true });Long pages can produce large image files and can take more time and memory to process than viewport captures. If you only need a specific part of a page, use a clip or capture the relevant element instead.
Capture a rectangular clip
Use clip to specify a rectangle with x, y, width, and height:
await page.screenshot({
path: 'region.png',
clip: { x: 0, y: 120, width: 800, height: 500 },
});Choose coordinates and dimensions that fit the page and viewport you intend to capture. Puppeteer documents that captureBeyondViewport defaults to false when no clip is supplied and true when a clip is supplied. If changing that option, account for how the clip and viewport interact rather than assuming both cases behave identically.
Capture one element
Find the element and invoke its screenshot method. For example:
const card = await page.waitForSelector('.product-card');
if (!card) throw new Error('Product card was not found');
await card.screenshot({ path: 'product-card.png' });Puppeteer attempts to scroll the element into view before capturing it. If the element is detached from the DOM before the operation completes, the screenshot call throws. This can happen on pages that replace or rerender nodes; locate the element near the capture step and handle the possibility that it disappears.
Choose format, quality, and background
Puppeteer documents PNG as the default output format. You can select a format with type, or let the path extension determine it. The documented quality setting ranges from 0 to 100 and does not apply to PNG.
await page.screenshot({
path: 'preview.jpeg',
type: 'jpeg',
quality: 80,
});Use an appropriate extension when saving by path, and be explicit with type if you want the requested image format to be clear in code. For transparent output, set omitBackground: true:
await page.screenshot({
path: 'transparent.png',
omitBackground: true,
});Transparency is useful when the screenshot is intended to be composited elsewhere; it is not a way to remove page content such as banners or widgets.
Wait for the page state you actually need
A navigation wait condition controls when Puppeteer considers navigation to have reached a particular stage; it does not establish that every site-specific component is ready for a screenshot. The official example uses networkidle2, but pages with polling, delayed assets, animations, or client-rendered content may need a more specific readiness check.
For an element-driven capture, wait for the target selector as in the element example above. For a page that renders content after navigation, identify a stable signal that represents the content you need, and wait for that signal before capturing. A fixed delay can be a fallback for known timing behavior, but it can be both slower and less reliable than waiting for a meaningful page condition.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Or skip the browser setup
If you need a screenshot endpoint instead of managing Puppeteer and a browser process, ScreenshotNeo accepts a URL in one GET request and returns a PNG, JPEG, WebP, or PDF. For example, save a WebP response with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Cookie banners are accepted and removed before capture, along with known consent platforms, newsletter popups, and chat widgets; those steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. An MCP server provides screenshot tools for AI agents, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to try it without a credit card.
Troubleshooting Puppeteer screenshot failures
The browser does not launch
Check that the Puppeteer package and its expected browser installation are present in the runtime environment. A locally installed package does not by itself guarantee that a separate deployment environment has the browser binary or dependencies it needs. Review the installation and launch error before changing screenshot options.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsRank #4
The screenshot is blank or missing expected content
The page may have navigated before the content you need was rendered. Confirm the target URL and wait for a meaningful selector or page state before capturing. Do not assume that a navigation wait condition means a client-rendered component, delayed image, or animation has settled.
The output file is not where expected
A relative path is resolved from the process’s working directory, which may differ from the script’s directory or your editor’s project root. Use an absolute path when the output location must be unambiguous. If no path is provided, the image remains returned data and Puppeteer does not create a file.
An element screenshot throws
Verify that the selector matches an element and that the element remains attached to the DOM through capture. On a frequently rerendered page, query close to the screenshot operation and be prepared to locate a replacement node if the original is detached.
The image is unexpectedly large or the wrong shape
Check whether fullPage is enabled, whether a clip was provided, and whether the page’s viewport is the intended size. A full-page image includes more content than a viewport capture; a clip captures only its specified rectangle. Use the scope that matches the downstream image requirement.
Performance, reliability, and cost considerations
Puppeteer makes screenshot generation a browser-automation task: your process must launch or reuse a browser, load the target page, wait for the state you need, and encode or save the result. The time and resource needs therefore depend on the target site, page state, capture dimensions, and runtime environment. The official documentation reviewed does not establish a universal performance figure, so benchmark your own URLs and concurrency levels before setting service limits.
-
Prefer a viewport or element capture when a full-page image is unnecessary; this limits the captured area and typically keeps resulting files smaller.
-
Use a page-specific readiness condition rather than applying one navigation wait rule as though every site renders the same way.
-
Always close browser instances when a job or worker is finished, including on error paths.
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 →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Account for browser runtime, memory, storage, and operational maintenance when comparing self-hosted automation with a screenshot service.
Puppeteer’s documentation search results identified version 25.12.0 on September 29, 2026; APIs and defaults can change, so check the current Page.screenshot API reference and ElementHandle.screenshot API reference when upgrading or investigating differences.
Frequently Asked Questions
Can Puppeteer capture a screenshot without writing a file?
Yes. Call page.screenshot() without a path; it returns image bytes as a Uint8Array.
Can Puppeteer take a screenshot of a single HTML element?
Yes. Select the element and call elementHandle.screenshot(); Puppeteer scrolls it into view if needed.
Windows 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 reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchDoes the screenshot quality option work for PNG?
No. Puppeteer documents quality as a 0–100 setting that does not apply to PNG.
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.
