What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Use page.screenshot(options) for a page capture and elementHandle.screenshot(options) for one DOM element. Set fullPage: true for the complete document, clip for a rectangle, type for the image format, quality for lossy formats, encoding: 'base64' when you need a string, and omitBackground: true when transparency is required. The examples below follow the Puppeteer API reference and guide; search results for the official documentation report version 25.12.0, but option defaults can change, so verify the current reference before pinning production code.
Choose the capture method first
Capture a page
The official guide’s instruction is: “For capturing screenshots use Page.screenshot().” A page screenshot operates on the current page and accepts a screenshot-options object. With no path, Puppeteer returns the image bytes to your program instead of writing a file.
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({
path: 'page.png',
fullPage: true,
});
await browser.close();
})();This saves a full-document PNG as page.png. A relative path is resolved from the process’s current working directory. If you omit path, the result remains in memory as a Uint8Array by default.
Capture one element
Call screenshot() on an ElementHandle when the target is a card, chart, logo, or another single DOM node. Puppeteer scrolls the target into view when necessary. The capture fails if that element has been detached from the DOM, so obtain the handle after the page has rendered the target and avoid replacing it before the call.
#1 Best Overall
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
const card = await page.$('.card');
if (!card) throw new Error('No .card element found');
await card.screenshot({ path: 'card.png' });
await browser.close();
})();Use the page API when the required scope is the document, a viewport region, or a clipped rectangle. Use the element API when the required scope is a particular node.
Screenshot options at a glance
| Goal | Option or method | Documented behavior |
|---|---|---|
| Capture the entire document | fullPage: true |
Captures a full-page screenshot; the default is false. |
| Capture a rectangle | clip |
Defines the region to capture. |
| Capture beyond the viewport | captureBeyondViewport |
Defaults to false without a clip and true when a clip is supplied. |
| Write a file | path: 'capture.png' |
Saves to that path; relative paths use the current working directory. Without path, no file is saved. |
| Select an image format | type |
PNG is the documented default. A file extension can infer the type when path is supplied. |
| Set lossy quality | quality: 0–100 |
Accepts values from 0 through 100 and does not apply to PNG. |
| Get a base64 string | encoding: 'base64' |
Returns a string instead of the default binary result. |
| Allow transparency | omitBackground: true |
Hides the default white background and permits transparent capture. |
| Capture a DOM node | elementHandle.screenshot(options) |
Scrolls the element into view and throws if the element is detached. |
See the complete ScreenshotOptions interface for the version you use.
Recipes for common capture requirements
Full page versus the current viewport
Without options, the screenshot is not automatically a full-document capture. Set fullPage: true when content below the viewport must be included. Leave it false when the viewport itself is the desired output.
await page.screenshot({ path: 'viewport.png' });
await page.screenshot({ path: 'entire-document.png', fullPage: true });Full-page output can be substantially taller than a viewport image. For very long documents, choose the output format and file destination deliberately and make sure the process has enough memory for the returned or encoded image.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →PNG, JPEG, and quality
PNG is the default. To request another documented image format, set type. The quality value is meaningful for lossy formats and is ignored for PNG. If you provide a path, the extension can be used to infer the screenshot type.
await page.screenshot({ path: 'interface.png', type: 'png' });
await page.screenshot({
path: 'interface.jpg',
type: 'jpeg',
quality: 82,
});Do not expect a lower or higher quality value to change a PNG; choose a format that supports the trade-off you need.
Save to disk or keep bytes in memory
Use path for a file artifact. Omit it to consume the returned Uint8Array in code, such as an upload or an HTTP response.
const bytes = await page.screenshot({ type: 'png' });
console.log(bytes instanceof Uint8Array);For a base64 payload, request the alternate encoding explicitly:
const base64 = await page.screenshot({
type: 'png',
encoding: 'base64',
});
console.log(typeof base64); // stringThe method reference documents a Promise<Uint8Array> result for ordinary calls and a string overload when encoding: 'base64' is selected.
Clip a rectangle
Set clip when only a rectangular portion of the page is needed. The clip describes the capture region rather than selecting a DOM node.
await page.screenshot({
path: 'region.png',
clip: {
x: 40,
y: 120,
width: 800,
height: 500,
},
});When a clip is supplied, the documented default for captureBeyondViewport is true. Set it explicitly when you need the behavior to be obvious to future maintainers.
await page.screenshot({
path: 'region-explicit.png',
clip: { x: 40, y: 120, width: 800, height: 500 },
captureBeyondViewport: true,
});Capture a transparent background
Chromium normally supplies a white background. Set omitBackground: true to hide that default and permit transparent pixels, which is useful for logos or overlays.
Recommended Free Tools
await page.screenshot({
path: 'logo.png',
omitBackground: true,
});Transparency is an appearance choice, not a format by itself; select an image type that preserves the alpha channel for the asset you are producing.
Combine options for an element
Element screenshots accept the same screenshot options relevant to the output, including a path, format, quality where supported, and background handling.
const chart = await page.$('#chart');
if (!chart) throw new Error('#chart is missing');
await chart.screenshot({
path: 'chart.webp',
type: 'webp',
quality: 90,
});Keep the handle valid until the call completes. If the application redraws the component by replacing its node, query it again before taking the screenshot.
Return values and browser coordination
A screenshot operation is asynchronous. Puppeteer’s documented coordination behavior matters when pages or contexts are created or closed while a capture is running: BrowserContext.newPage(), Browser.newPage(), and Page.close() automatically wait for the screenshot to finish. Page.bringToFront() does not wait for existing screenshot operations. Design cleanup around those guarantees rather than assuming every page-management call is a synchronization point.
The official method and guide pages are Page.screenshot() and the Screenshots guide. The element-specific contract is documented at ElementHandle.screenshot().
A practical decision checklist
- Scope: choose page capture for a document,
clipfor coordinates, or an element handle for one DOM node. - Extent: set
fullPage: truefor the complete document; otherwise capture the viewport or defined region. - Output: use
pathfor a file, omit it for aUint8Array, or request base64 explicitly. - Format: use PNG when lossless output is appropriate; select another documented type when size or compatibility requires it.
- Quality: apply the 0–100 setting only to formats for which quality is supported; it has no effect on PNG.
- Background: enable
omitBackgroundonly when transparent pixels are part of the requirement. - Version: confirm defaults against the API reference for the Puppeteer version installed in your project.
Troubleshooting Puppeteer screenshots
The image is only the visible viewport
Cause: fullPage defaults to false. Fix: pass fullPage: true to page.screenshot().
Rank #4
The clip does not include the expected area
Cause: the rectangle is defined by the supplied clip values, and viewport-extension behavior has not been made explicit. Fix: verify the rectangle’s coordinates and dimensions, then set captureBeyondViewport: true or false intentionally.
Changing quality does nothing
Cause: quality is not applicable to PNG. Fix: choose a supported lossy format before tuning its 0–100 quality value.
No file appears
Cause: no path was supplied, so Puppeteer returned the image in memory. Fix: provide a path, or handle the returned bytes/base64 value in your application.
The screenshot fails for an element
Cause: the ElementHandle was detached from the DOM. Fix: locate the current node again after rendering or rerendering, then call elementHandle.screenshot().
Transparent output still looks white
Cause: the default background was not omitted, or the selected output path does not preserve transparency. Fix: set omitBackground: true and use an image type suitable for alpha transparency.
Cleanup races with a capture
Cause: code assumes that every page-management method waits for screenshots. Fix: rely on the documented waits for new-page and close operations; do not use bringToFront() as a wait.
Or skip the browser setup
If you need screenshots as an HTTP service rather than maintaining Chromium code, ScreenshotNeo is the first alternative to try: it produces clean shots, bills only clean captures, and its paid entry plan is $5 for 3,000 shots.
One GET request returns a PNG, JPEG, WebP, or PDF. The API accepts the URL as a parameter:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the complete ScreenshotNeo documentation for options and response details. Equivalent calls in Python and Node.js are:
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}`);Before capture, ScreenshotNeo accepts the cookie or consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and whether the request was billed. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
Free tools Windows power users keep installed
One-click scans. No signup required.
All features are included on every plan. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to begin.
Reference links and version caution
Use the ScreenshotOptions reference for option names and defaults, the official screenshots guide for usage patterns, and the method references for pages and elements. The documentation search results report Puppeteer 25.12.0; because these contracts can change, check the reference that matches your installed release.
Frequently Asked Questions
Does Page.bringToFront() wait for a screenshot already in progress?
No. The documented coordination behavior says bringToFront() does not wait for existing screenshot operations.
What does Puppeteer return when I request base64 encoding?
With encoding: 'base64', the screenshot method returns a string rather than the default Uint8Array.
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 problemsQuick 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.
