Capture a Webpage Screenshot with a Transparent Background in Puppeteer

Set omitBackground: true in page.screenshot() to hide Chromium’s default white background and allow a transparent screenshot. Use PNG, the default format, because it supports transparency. If the page itself paints a background color or image, that authored background remains rendered content; make the relevant page background transparent if you need those areas transparent too.

Capture a transparent screenshot with Puppeteer

Install Puppeteer in a Node.js project, then navigate to the page and pass omitBackground: true when taking the screenshot. This example captures the full page:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.goto('https://example.com', { waitUntil: 'networkidle2' });

  await page.screenshot({
    path: 'capture.png',
    type: 'png',
    fullPage: true,
    omitBackground: true,
  });
} finally {
  await browser.close();
}

Run it in a project configured for ES modules, for example with "type": "module" in package.json. You can also use CommonJS by replacing the import with const puppeteer = require('puppeteer'); and running the script from a CommonJS project. The API option is documented in Puppeteer’s ScreenshotOptions reference.

What omitBackground changes

Puppeteer documents omitBackground as hiding the default white background and allowing screenshots with transparency. PNG is the default screenshot type, so type: 'png' is optional but makes the desired output explicit.

The option removes the browser’s default background; it does not erase backgrounds deliberately drawn by the page’s CSS. If a page sets body { background: white; }, those pixels are part of the page rendering. To get transparent areas, adjust the page’s own background styles as appropriate before taking the screenshot. For example, if you control the page, you might add a transparent background rule to the target content. Whether this is suitable depends on that page’s layout and styling.

Choose the capture area

Goal	Option or method	What to expect
Visible viewport	Default page.screenshot()	Captures the current viewport.
Entire page	fullPage: true	Requests a full-page screenshot. Long pages can use more memory and take longer to capture.
One element	ElementHandle.screenshot()	Captures the selected element’s bounds; use a selector that identifies the intended element.

The page screenshot API documents fullPage, and Puppeteer’s guide demonstrates ElementHandle.screenshot() for an individual element. Keep omitBackground: true in the screenshot options for either capture scope.

// Capture one element with a transparent browser background.
const card = await page.waitForSelector('.product-card');
if (!card) throw new Error('Product card was not found');

await card.screenshot({
  path: 'product-card.png',
  omitBackground: true,
});

See the Puppeteer screenshot guide for element capture and the options reference for page screenshot settings.

Important options and practical details

• omitBackground: Set to true to omit the default white background.
• type: PNG is the default and supports transparency. Do not choose a format that cannot represent alpha transparency if transparent pixels are required.
• path: Writes the image to a file. Without a path, Puppeteer returns screenshot data instead.
• fullPage: Set to true when the capture should include the whole page rather than just the viewport.
• Element screenshot: Use an element handle when only a specific component should be captured.
• Navigation readiness: Choose a suitable waitUntil condition for the page. networkidle2 can be useful for many pages, but pages with continuous network activity may never become idle; in that case use another readiness condition and explicitly wait for the content you need.

Troubleshooting transparent captures

Symptom	Likely cause	Fix
The output has a solid white background.	omitBackground is missing or false, or the page paints a white background itself.	Set omitBackground: true. If the page’s CSS paints white, change the relevant page background style where you control it.
The image has no transparency when opened in a viewer.	The selected output format or downstream image handling does not preserve alpha, or the captured content covers the full area.	Save as PNG and inspect it with a tool that shows transparency. Check the page’s authored backgrounds and the image processing steps after capture.
The page is blank or partly rendered.	The screenshot was taken before navigation or client-side content finished rendering.	Wait for an appropriate navigation condition and then wait for a relevant selector or page-specific readiness signal before capturing.
The script hangs waiting for navigation.	A page with persistent connections may not reach a network-idle condition.	Use a different waitUntil condition, such as domcontentloaded, and wait for a specific element instead.
The selected element cannot be captured.	The selector does not match, or the element is not available yet.	Wait for the selector, check that it exists, and verify that it identifies the intended element.
Full-page capture is slow or memory-heavy.	The document is very long or contains large images and complex content.	Capture only the needed element or viewport where possible, and avoid taking many large full-page screenshots concurrently.

Performance, reliability and cost

For a single local capture, Puppeteer requires a running browser and the resources to load and render the target page. Full-page images generally require more work than viewport or element captures, especially for tall documents. Reuse a browser process for batches of captures when appropriate, while creating a separate page per job and closing pages and the browser cleanly. Set navigation and operation timeouts that fit your workload, and handle navigation failures so one unavailable site does not stop a batch.

The result depends on the page’s availability, rendering behavior, network requests and any access checks it presents. A screenshot is a rendering snapshot, so dynamic content can vary between runs. Puppeteer itself is the browser automation approach; this method does not add an external screenshot API charge, though it does use your own compute and bandwidth.

Or skip the browser setup

ScreenshotNeo is a website screenshot API: one GET request returns an image or PDF. For supported pages, its clean-shot flow accepts cookie and 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 cost nothing, and response headers indicate the page verdict and whether the shot was billed. It also offers an MCP server with screenshot, page-info and PDF tools for AI agents.

For API options and parameters, see the ScreenshotNeo docs. This basic request saves the returned image as a file:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python equivalent:

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)

Node.js equivalent:

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(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

These examples use the API’s default output behavior; consult the docs for format and other capture options. ScreenshotNeo’s published plans include 1,000 screenshots per month free with no card, then paid plans starting at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Does omitBackground make every white pixel transparent?

No. It omits Chromium’s default white background; white pixels painted by the page remain page content.

Can I capture just one component?

Yes. Select it and call ElementHandle.screenshot(), passing omitBackground: true in the options.

Do I need to set type to PNG?

PNG is Puppeteer’s documented default screenshot type. Setting type: 'png' explicitly can make the output intent clearer.

Which Puppeteer version is this based on?

The cited API reference identifies version 25.12.0. Check the documentation and type definitions for the version installed in your project if they differ.