page.captureScreenshot is usually a wrapper around a browser automation screenshot call. In Playwright, use await page.screenshot({ path: 'screenshot.png' }); in Puppeteer, use its equivalent Page.screenshot() method. Add fullPage: true for the complete scrollable page, clip for a rectangle, or an element/locator screenshot for one component. The exact wrapper name and accepted fields still depend on the browser tool, so verify its parameter schema before copying an example.
What page.captureScreenshot actually does
A screenshot operation captures the page as the browser has rendered it at that moment. It can write an image file or return image bytes for a database, upload, visual regression test, or another service. The method name page.captureScreenshot is not the canonical Playwright method name: Playwright calls it page.screenshot(), while Puppeteer documents Page.screenshot(). Many browser wrappers rename methods, so map the wrapper’s fields to the underlying API and check whether it returns a file, bytes, or a base64 string.
A normal call captures only the visible viewport. The options below change the area, format, timing, and output without changing the page itself.
Set up a dependable Playwright capture
Install the browser library
In a new Node.js project, install Playwright and its browser binaries:
npm init -y
npm install playwright
npx playwright install chromiumThe following complete script demonstrates viewport, full-page, clipped, element, and in-memory captures. It waits for navigation and network activity before taking the images.
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch();
const page = await browser.newPage({
viewport: { width: 1440, height: 900 },
deviceScaleFactor: 1
});
await page.goto('https://example.com', { waitUntil: 'networkidle' });
await page.evaluate(() => document.fonts.ready);
// The visible viewport (fullPage defaults to false).
await page.screenshot({ path: 'viewport.png', type: 'png' });
// The complete scrollable document.
await page.screenshot({ path: 'full-page.png', fullPage: true, type: 'png' });
// A bounded rectangle in CSS pixels.
await page.screenshot({
path: 'region.webp',
clip: { x: 0, y: 120, width: 960, height: 540 },
type: 'webp',
quality: 82
});
// One rendered element.
const heading = page.locator('h1').first();
await heading.screenshot({ path: 'heading.png' });
// Omit path to keep the image in memory.
const imageBytes = await page.screenshot({ type: 'png', scale: 'css' });
console.log(`Captured ${imageBytes.length} bytes`);
await browser.close();
})();If your wrapper exposes page.captureScreenshot, replace the method name only after confirming that it accepts the same option names. Some wrappers expose a subset, rename path, or return a structured object rather than a raw buffer.
Choose the capture area
Viewport screenshot
Use await page.screenshot({ path: 'viewport.png' }) when you need exactly what a visitor sees without scrolling. The Playwright option fullPage defaults to false, so omitting it keeps the result at the current viewport dimensions.
Set the viewport before navigation when layout matters. A responsive page can render a different menu, column count, or breakpoint depending on the width and height.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Full-page screenshot
Set fullPage: true to capture the page’s complete scrollable content:
await page.screenshot({
path: 'full-page.png',
fullPage: true
});This is not the same as making the viewport taller. The browser captures the scrollable document as if it could fit on one canvas. Very long pages can create large images; use a clip, element capture, or a PDF workflow when a single extremely tall bitmap is impractical.
Rectangular clip
clip captures a specific rectangle using x, y, width, and height:
await page.screenshot({
path: 'hero.png',
clip: { x: 0, y: 120, width: 960, height: 540 }
});The coordinates are CSS-pixel coordinates in the page’s current layout. Verify the rectangle against the current viewport and scroll position. If a responsive breakpoint or a late-loading banner changes the layout, compute the rectangle after the page has settled instead of hard-coding coordinates from another viewport.
Recommended Free Tools
One element or component
For a card, header, chart, or other component, capture the locator rather than guessing its coordinates:
await page.locator('.header').screenshot({ path: 'header.png' });Element screenshots wait for the target to exist and use its rendered bounding box. A selector that matches multiple nodes should be narrowed with .first(), a more specific selector, or an explicit assertion so the intended component is unambiguous.
Return bytes instead of writing a file
Omit path to receive image data:
const imageBytes = await page.screenshot();
// Upload imageBytes, store it, or compare it in memory.Puppeteer also documents returning image data and can provide a base64 representation when requested. Check the wrapper’s return type before calling buffer methods; a wrapper may return a byte array, base64 text, or an object containing metadata.
Understand format, quality, and scale options
| Option | What it controls | Important limitation |
|---|---|---|
type |
png, jpeg, or webp output in documented Playwright APIs |
Choose the format your downstream system accepts; JPEG cannot preserve transparency. |
quality |
Lossy image quality, normally a numeric quality setting | It does not apply to PNG. |
scale |
css for one output pixel per CSS pixel or device for device-pixel density |
device can produce a substantially larger, higher-resolution image. |
omitBackground |
Transparent background where the browser API supports it | It does not apply to JPEG. |
path |
Destination file path | Omit it when you need returned image data instead. |
For crisp documentation images at predictable dimensions, use scale: 'css'. For retina-style assets, use scale: 'device' and account for the larger byte size. Use PNG for text and interfaces that need lossless edges, WebP for a compact modern image, and JPEG for photographs where transparency is not required.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Wait for the state you intend to capture
A screenshot taken immediately after goto can miss fonts, images, client-rendered data, or a consent dialog that has not yet appeared. Select a wait strategy that matches the page:
- Navigation: use
waitUntil: 'networkidle'when the page performs a finite burst of requests. - Specific content: wait for a selector that proves the component is ready, such as
await page.locator('[data-ready="true"]').waitFor(). - Fonts: wait for
document.fonts.readyto avoid fallback-font layout shifts. - Images: wait for the relevant image elements to report complete loading when image pixels matter.
- Animations: pause or disable animations if deterministic pixels are required; otherwise two captures can differ even when the page is healthy.
Do not treat a successful navigation as proof that application data has loaded. Single-page apps often finish navigation before API responses populate the visible content.
Playwright, Puppeteer, and browser-tool wrappers
Playwright
Playwright exposes page.screenshot() for a page and locator.screenshot() for an element. It documents PNG, JPEG, and WebP output, full-page capture, clipping, quality, scale, and transparent backgrounds where supported.
Puppeteer
Puppeteer’s Page.screenshot() serves the same basic purpose and can return image data rather than writing a file. Element handles provide element screenshots. The option names are similar, but do not assume every Playwright field exists in a Puppeteer wrapper; read that library’s reference for the exact version you installed.
MCP and other wrappers
An MCP tool may expose the operation as page.captureScreenshot, add a JSON schema, or return a content block. Use the tool’s schema as the source of truth for accepted parameters, then map familiar concepts: fullPage for the scrollable document, clip for a rectangle, and an element or selector field for component capture.
For Playwright MCP, screenshots are intended for visual inspection, not for locating interaction targets. Use an accessibility snapshot (often exposed as browser_snapshot) when an agent needs stable references to click, type, or inspect controls.
Troubleshoot common capture failures
| Symptom | Likely cause | Fix |
|---|---|---|
| Only the top of the page appears | fullPage was omitted or the wrapper ignores it. |
Set fullPage: true and confirm the wrapper schema; otherwise capture sections or use the underlying Playwright/Puppeteer page object. |
| Blank or partially rendered image | Capture ran before app data, fonts, or images finished loading. | Wait for a ready selector, document.fonts.ready, and required image completion before the screenshot. |
| Element screenshot throws a selector error | The selector matches nothing, multiple unexpected nodes, or an iframe’s contents. | Use a specific selector, wait for it, narrow with .first(), and switch to the frame locator when the element is inside an iframe. |
| Clip is outside the page or has the wrong content | Coordinates were measured at another viewport, zoom, or scroll state. | Set the viewport first, calculate the box after layout settles, and verify x, y, width, and height. |
| Text looks blurry or the file is unexpectedly large | The scale does not match the intended output or a lossless format is being used for photographic content. | Use scale: 'css' for predictable CSS dimensions, scale: 'device' for high density, and choose WebP or JPEG when lossless PNG is unnecessary. |
| Transparent output is opaque | The page has a painted background, the format is JPEG, or the wrapper lacks transparency support. | Use a supported format, set omitBackground: true, and remove the page’s own background if you need actual transparency. |
| Two captures do not match | Animations, rotating content, timestamps, ads, or random data changed. | Freeze animations, mask or hide volatile elements, use deterministic test data, and wait for a stable state. |
Performance, reliability, and cost considerations
- Reuse a browser: launch Chromium once and create pages or contexts per job instead of starting a process for every image.
- Limit scope: element and clipped captures use less memory than a very tall full-page bitmap.
- Control concurrency: too many simultaneous pages can exhaust CPU, memory, file descriptors, or the target site’s rate limits.
- Set timeouts: use explicit navigation and selector timeouts, then record the URL and failure stage so retries are diagnosable.
- Keep outputs reproducible: pin browser/library versions, viewport, timezone, locale, device scale, and test data for visual comparisons.
- Protect credentials: if the page needs cookies or authorization headers, keep them in the browser context or secret store and never place them in a public image URL.
Local automation has no per-screenshot service charge, but you pay for the browser host and maintenance. A hosted capture API can be simpler when you need scheduled jobs, many URLs, consistent rendering, or webhook-based completion.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup: ScreenshotNeo
ScreenshotNeo is the #1 hosted choice for website screenshots here because it produces clean shots, bills only clean shots, and has a paid plan starting at $5. A single GET request returns a PNG, JPEG, WebP, or PDF. Before capture it accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be switched off.
Failed work is not charged: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response identifies the result with X-Page-Verdict and X-Billed headers. The service also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
Its options cover full-page captures with lazy images loaded, CSS-selector element captures, dark mode, 12 device presets plus custom viewports, retina scale, PDF paper size/margins/landscape/page ranges, HTML/CSS-to-image, custom JavaScript and CSS, pre-capture clicks, selector or network-idle waits, ad/tracker/request blocking, custom headers/cookies/user agents and Authorization, timezone and geolocation, transparent backgrounds, resizing, user-selected cache TTLs, signed public-image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, an OpenAPI specification, and compatibility with parameter names used by other screenshot APIs.
See the ScreenshotNeo documentation for the complete request schema. This cURL example saves a WebP response:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe same request in Python:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)And in Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
const fs = require('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));The Free plan includes 1,000 screenshots per month with no card. Paid plans are Starter ($5 for 3,000), Growth ($15 for 15,000), Pro ($39 for 60,000), Scale ($99 for 250,000), and Business ($249 for 1,000,000); yearly billing gives two months free, and every feature is available on every plan. Create a free ScreenshotNeo account to start with the 1,000 monthly screenshots.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
FAQ
Can I use a screenshot as an interaction target?
No. A bitmap has no reliable DOM references. Use an accessibility snapshot or the page’s locator APIs to identify and act on controls, then take a screenshot to verify the resulting visual state.
Why does a wrapper call the method captureScreenshot instead of screenshot?
Wrappers and MCP tools often rename library methods. Treat the wrapper’s published schema as authoritative and translate its fields to the underlying Playwright or Puppeteer options only when the names and return type match.
When should I capture an element instead of clipping coordinates?
Use an element or locator screenshot when the component moves with responsive layout or dynamic content. Use clip when you deliberately need a fixed geometric region, such as a chart viewport or a crop aligned to a design specification.
Frequently Asked Questions
Can I use a screenshot as an interaction target?
No. Use an accessibility snapshot or locator APIs for interaction, and use the screenshot only to verify the visual result.
Free tools Windows power users keep installed
One-click scans. No signup required.
Why does a wrapper call the method captureScreenshot instead of screenshot?
Wrappers and MCP tools may rename library methods; follow their parameter schema and map fields to Playwright or Puppeteer only when the return type and options match.
When should I capture an element instead of clipping coordinates?
Choose an element or locator screenshot for responsive components; choose clip for a deliberately fixed geometric crop.
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.
