Chrome Headless Screenshot with Transparent Background: How to Enable It

Short answer: Chrome’s documented Headless command-line options include --screenshot, but the CLI reference does not document a transparency flag. For an alpha-transparent screenshot, use Puppeteer or Playwright, set omitBackground: true, and save as PNG. This omits Chrome’s default white background; it cannot make page content transparent if the page’s CSS paints an opaque background.

1. What “transparent background” means

A transparent PNG stores an alpha channel, so pixels can reveal whatever is behind the image when you place it on another background. The screenshot API option hides the browser’s default white background. The page can still paint its own background with CSS, so transparency depends on both the screenshot option and what the page renders.

Use PNG for this workflow. Playwright documents that omitBackground does not apply to JPEG, which does not support alpha transparency. The documented default for omitBackground is false in both Puppeteer and Playwright.

2. Use Puppeteer

Install Puppeteer and save this as screenshot.mjs. Puppeteer’s documented default screenshot format is PNG, and setting omitBackground to true hides the default white background.

npm install puppeteer

import puppeteer from 'puppeteer';

const url = process.argv[2] ?? 'https://example.com';
const browser = await puppeteer.launch({ headless: true });

try {
  const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
  await page.goto(url, { waitUntil: 'networkidle2', timeout: 30_000 });
  await page.screenshot({ path: 'capture.png', type: 'png', omitBackground: true });
  console.log('Saved capture.png');
} finally {
  await browser.close();
}

Run it with node screenshot.mjs https://example.com. If you control the page, remove or override any opaque background on the page or the element being captured. For a page you do not control, omitBackground alone cannot guarantee transparent pixels where the page itself paints a color.

Relevant option: omitBackground defaults to false; set it to true when you want the browser’s default background omitted. Use PNG output for alpha. See the Puppeteer ScreenshotOptions reference.

3. Use Playwright

Install Playwright and its Chromium browser, then save this as screenshot.mjs. Playwright’s Page screenshot API documents omitBackground: true for transparency.

npm install playwright
npx playwright install chromium

import { chromium } from 'playwright';

const url = process.argv[2] ?? 'https://example.com';
const browser = await chromium.launch({ headless: true });

try {
  const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
  await page.goto(url, { waitUntil: 'networkidle', timeout: 30_000 });
  await page.screenshot({ path: 'capture.png', type: 'png', omitBackground: true });
  console.log('Saved capture.png');
} finally {
  await browser.close();
}

Run it with node screenshot.mjs https://example.com. Choose PNG; Playwright says omitBackground is not applicable to JPEG. See the Playwright Page API reference.

4. Can the Chrome Headless CLI do it?

The Chrome Headless command-line reference documents --screenshot, --window-size, and --timeout, including an example that combines screenshot capture with a window size. It does not document a transparent-background flag. If alpha transparency is required, use a documented screenshot API such as Puppeteer or Playwright.

This describes the checked CLI reference; it is not a claim that no lower-level or future implementation-specific route could exist. The CLI is still suitable for simple command-line captures when transparency is not needed.

5. Keep the page background from being painted

omitBackground removes the browser’s default white background, not an explicit background painted by the website. If you own the page, configure its CSS to leave the area you want transparent unpainted. For a page you do not control, page styles may fill the body, a container, or the captured element with an opaque color.

For a controlled page, you can inject CSS before capture with either library. For example, in Puppeteer:

await page.addStyleTag({ content: `
  html, body {
    background: transparent !important;
  }
` });
await page.screenshot({ path: 'capture.png', type: 'png', omitBackground: true });

Only use this override when it is appropriate for the page. It may not clear backgrounds applied to nested elements, pseudo-elements, images, or canvas content. Inspect the rendered page and adjust the specific styles you control.

6. Choose the right route

Route	Transparency control	Format	Best fit
Chrome Headless CLI	No flag is documented in the checked CLI reference	Documented screenshot output is PNG	Simple command-line capture when alpha is not required
Puppeteer	`omitBackground: true`	PNG is the documented default; specify PNG explicitly for clarity	Node browser automation
Playwright	`omitBackground: true`	Use PNG; the option does not apply to JPEG	Browser automation or test workflows

For a single capture, either automation library can express the setting directly. Choose based on the browser automation already used by your project; the transparency switch is the same.

7. Common problems and fixes

Symptom	Likely cause	Fix
The output still looks white	The page or an element paints a white CSS background, or the viewer displays transparency as white	Inspect the PNG over a colored background and check page styles. Clear only the backgrounds you control.
The image has no alpha transparency	The output was encoded as JPEG or the screenshot option was omitted	Save as PNG and pass `omitBackground: true`.
The API rejects the option	The installed library or version may differ from the referenced API, or the option was placed on the wrong call	Check the installed library’s screenshot API and pass the setting to `page.screenshot()`.
The capture is blank or incomplete	Navigation may have timed out, or the page may still be loading dynamic content	Check the URL and navigation errors. Wait for the relevant page state or a known selector before taking the screenshot.
Command-line output is opaque	The documented CLI screenshot options do not include a transparency flag	Use Puppeteer or Playwright when you need the documented `omitBackground` control.

8. Performance, reliability, and cost

For occasional captures, launching a browser per run is straightforward. For repeated captures in a service, reuse browser processes where your architecture permits and create a separate page or context for each job; always close pages and browsers when finished. Keep navigation timeouts bounded, and wait for the page state your capture actually needs rather than relying on an unnecessarily long fixed delay.

Transparent output does not itself require a different capture workflow beyond PNG and the background option. PNG files can be larger than JPEG because PNG is lossless, so consider the storage and transfer cost when capturing many large pages. JPEG is not an option when alpha transparency is required.

Browser automation runs on your own compute, so cost depends on the machines and runtime you operate. The cited browser documentation does not provide a performance benchmark or service cost comparison. Version-specific behavior should be checked against the installed browser and automation library.

9. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from ScreenshotNeo. One GET request returns a PNG, JPEG, WebP, or PDF. The API supports transparent backgrounds; see the ScreenshotNeo API docs for request options and configuration.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -d format=png \
  -d transparent=true \
  -o shot.png

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={
        "access_key": "YOUR_API_KEY",
        "url": "https://stripe.com",
        "format": "png",
        "transparent": "true",
    },
    timeout=90,
)
r.raise_for_status()
open("shot.png", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com',
  format: 'png',
  transparent: 'true'
});
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.png', Buffer.from(await res.arrayBuffer())));

Cookie banners are accepted like a visitor and removed along with 60+ known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. See all options at the docs.

10. FAQ

Does a transparent screenshot require a transparent website?

The page does not need to be designed as a transparent image, but any CSS background it paints remains in the screenshot. The area you want transparent must not be painted opaquely.

Can I use JPEG and keep transparency?

No. Use PNG when the output needs alpha transparency.

Does the documented Chrome Headless CLI support a transparency flag?

The checked CLI reference does not document one. Puppeteer and Playwright document omitBackground for this use.

Which automation library should I choose?

Use the one your project already depends on. Both Puppeteer and Playwright document omitBackground: true on the page screenshot API.