Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesUse ElementHandle.screenshot() to capture one DOM element in Puppeteer. It scrolls the element into view by default, then captures it through Page.screenshot(). The result is a Uint8Array unless you request base64 encoding; a detached element causes the call to fail. The options let you control saving, format, transparency, clipping, and scrolling.
Capture an element with Puppeteer
Wait for the element, then call its screenshot method. This example saves a PNG to the current working directory:
const element = await page.waitForSelector('div');
if (!element) throw new Error('Element not found');
await element.screenshot({ path: 'div.png' });The selector is only an example; replace it with a selector for the element you want. waitForSelector() can return null if it does not find a match, so checking the result avoids calling the method on a missing handle. The official guide demonstrates this pattern and notes that the element is scrolled into view if needed: Puppeteer screenshots guide. API behavior and option defaults below are documented for Puppeteer 25.12.0; check the reference for the version installed in your project.
Element screenshot options
ElementHandle.screenshot() accepts the shared screenshot controls and the element-specific scrollIntoView option. Choose settings for the output you need rather than assuming one combination is universally best.
#1 Best Overall
| Option | What it controls | Documented default or behavior |
|---|---|---|
scrollIntoView |
Whether Puppeteer scrolls the element into view before capture. | true. |
type |
Image format. | 'png'. |
quality |
Quality setting for formats where it applies. | Number from 0 to 100; not applicable to PNG. No default is listed. |
path |
Saves the capture to a file. | Format is inferred from the filename extension. Relative paths are resolved from the current working directory. Without a path, no file is saved. |
encoding |
Representation returned to your code. | 'binary'; use 'base64' for a string result. |
omitBackground |
Hides the default white background for transparency. | false. |
clip |
Limits the capture to a specified screenshot region. | Optional ScreenshotClip; no default is listed. |
captureBeyondViewport |
Whether to capture beyond the viewport. | false without a clip and true with one. |
fullPage |
Requests a full-page screenshot. | false. |
fromSurface |
Chooses surface capture rather than view capture. | true. |
optimizeForSpeed |
Requests speed-oriented capture. | false; the API table gives no further explanation. |
For the complete, version-specific option definitions, see the ElementScreenshotOptions reference and ScreenshotOptions reference.
Choose the right output and page behavior
Save a file or keep bytes in memory
Set path when Puppeteer should write a file. An extension such as .png indicates the file format. Omit path when the calling code should handle the returned image data instead. By default, that data is a binary Uint8Array; setting encoding: 'base64' selects a string return value.
Pick a format and quality
PNG is the documented default. Set type to request another supported image format; quality accepts a number from 0 through 100 but does not apply to PNG. The API reference does not prescribe a universally best quality value, so select it based on the requirements of the destination consuming the image.
Capture transparency or a region
Use omitBackground: true to hide the default white background. Use clip when you need a defined screenshot region. The clip is a general screenshot control, not a substitute for selecting the correct DOM element.
Recommended Free Tools
Rank #3
Control automatic scrolling
By default, Puppeteer scrolls the element into view before capturing it. Set scrollIntoView: false if changing the page’s scroll position is undesirable. If the target is outside the viewport, disabling the scroll may affect whether the element can be captured as expected; the API documents the setting but does not guarantee a particular visual outcome for every page.
Return the screenshot without saving it
When the image should remain in memory, omit path. The returned value is binary by default; this example requests base64 explicitly:
const element = await page.waitForSelector('#receipt');
if (!element) throw new Error('Receipt element not found');
const imageBase64 = await element.screenshot({ encoding: 'base64' });Without the encoding override, the method returns a Uint8Array. Use the representation that suits the next step in your application; base64 is not required merely to receive an image.
Troubleshoot common failures
- The selector did not produce an element: check the selector and ensure the page has reached the state where the target exists. Handle a
nullresult fromwaitForSelector()before callingscreenshot(). - The method throws because the element was detached: the handle no longer refers to an element in the DOM. Locate the element again after the page update and take the screenshot using the fresh handle. Puppeteer’s method reference documents detachment as an error condition: ElementHandle.screenshot() reference.
- The page scroll position changes: this is the default behavior. Pass
scrollIntoView: falsewhen you need to avoid Puppeteer’s automatic scroll. - No file appears: confirm that
pathis present and that its directory is writable. A relative path is resolved from the process’s current working directory. - The output is not transparent: set
omitBackground: true; its default isfalse. - A quality setting has no effect:
qualitydoes not apply to PNG. Check the chosen image type and its supported options in the reference for your installed Puppeteer version.
Or skip the browser setup
If you need a screenshot from a URL rather than a DOM handle inside your Puppeteer session, ScreenshotNeo offers a one-request screenshot API. For example, save a WebP capture of a page with cURL:
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
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 documentation for API options. It removes cookie and consent banners, 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 response headers report the page verdict and billing status. Its MCP server provides screenshot tools for AI agents, including Claude and Cursor. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan.
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.
