How to make an HTML screenshot with a transparent background in Playwright
Use Playwright’s `omitBackground: true` option to capture a transparent PNG. Learn how it works for pages, elements, and visual assertions—and why a screenshot may still look white.
Set omitBackground: true in Playwright’s screenshot options and save as PNG. For a page, use page.screenshot(); for one element, use locator.screenshot(). The option hides the browser’s default white background. It does not remove backgrounds deliberately set by the page, and it does not work with JPEG. Playwright page screenshot documentation.
1. Set up a runnable Playwright example
This JavaScript example launches Chromium, opens a page, and writes a transparent PNG. Install Playwright and its browser first:
npm install playwright
npx playwright install chromiumSave this as screenshot.mjs and run it with node screenshot.mjs:
import { chromium } from 'playwright';
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
try {
await page.goto('https://example.com', { waitUntil: 'networkidle' });
await page.screenshot({
path: 'page.png',
type: 'png',
omitBackground: true,
});
} finally {
await browser.close();
}omitBackground is the setting that requests transparency. Explicitly selecting PNG makes the intended output format clear; PNG supports an alpha channel. Playwright documents PNG, JPEG, and WebP screenshot formats, but excludes JPEG from support for omitBackground.
2. Choose page, full-page, or element capture
Capture the current viewport
The example above captures the visible viewport. This is the default page screenshot scope.
Capture the full scrollable page
Set fullPage: true to capture the whole page rather than just the current viewport:
await page.screenshot({
path: 'full-page.png',
type: 'png',
fullPage: true,
omitBackground: true,
});Capture one element
Use a locator screenshot when the output should contain a specific matched element. Wait for the target to exist and be visible when the page renders it asynchronously:
const card = page.locator('#target');
await card.waitFor({ state: 'visible' });
await card.screenshot({
path: 'element.png',
type: 'png',
omitBackground: true,
});The locator screenshot API supports the screenshot options, including omitBackground. See the Locator API.
3. Use transparent screenshots in Playwright Test
For visual assertions in the Playwright Test runner, pass the option to toHaveScreenshot:
import { test, expect } from '@playwright/test';
test('page screenshot has a transparent background', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot({ omitBackground: true });
});This is a Playwright Test assertion workflow; it is separate from directly saving a screenshot with page.screenshot(). The runner manages its screenshot comparison and baseline workflow. See PageAssertions.
4. Understand what becomes transparent
omitBackground: true hides the browser’s default white canvas background. It does not erase a background color or image that the site explicitly paints on the body, a container, or the target element. That follows from the option’s documented scope: suppressing the default background, rather than removing page styling.
If authored styling is the cause, change the page’s CSS for the capture or inject a narrowly scoped override before taking the screenshot. For example, only use this if you intend to remove the page background:
await page.addStyleTag({
content: 'html, body { background: transparent !important; }',
});
await page.screenshot({ path: 'page.png', omitBackground: true });This override affects the rendered page and may change how components look. If only a particular container has a background, target that container instead of broadly changing html and body.
5. Pick a compatible image format
| Format | Transparency with omitBackground |
Use |
|---|---|---|
| PNG | Yes | Safest default when broad compatibility and transparency matter. |
| JPEG | No | Use only when transparency is not needed. |
| WebP | Playwright supports the format; confirm your downstream tools accept transparent WebP. | Consider when your image pipeline supports it. |
Playwright’s screenshot API accepts PNG, JPEG, and WebP types; its documentation specifically says omitBackground does not apply to JPEG. Prefer PNG unless you have verified that every consumer in your pipeline handles transparent WebP as expected. See Page screenshot options.
6. Troubleshoot a screenshot that still looks white
| Symptom | Likely cause | Fix |
|---|---|---|
| The output is JPEG. | JPEG does not support this transparency option. | Save as PNG and use a .png path. |
| The PNG looks white in an image viewer. | The viewer may display transparent pixels over white, or the page may paint a white background. | Inspect the alpha channel or place the image over a contrasting background in a viewer that shows transparency. Check for authored CSS backgrounds. |
| The page area is transparent but a panel remains opaque. | The panel or one of its ancestors has a CSS background. | Remove or override only the background that should disappear, then capture again. |
| An element screenshot fails or is empty. | The locator may not match, or its element may not be visible yet. | Check the selector and wait for the locator to become visible before calling screenshot(). |
| The screenshot differs between machines. | Rendering can vary with operating system, browser version, settings, hardware, power source, and headless mode. | Keep the execution environment consistent for screenshot comparisons. See Visual comparisons. |
7. Keep visual captures reliable
- Choose the capture scope deliberately: viewport, full page, or one locator.
- Wait for the page content you need before capture. For elements loaded later, wait for the locator to be visible.
- Use PNG when the output must reliably preserve transparency across common tools.
- Keep browser version, operating system, headless mode, and other rendering conditions consistent when comparing screenshots.
- Remember that a page’s own CSS background remains part of the rendered content unless you change that styling.
Playwright notes that visual output can vary across execution environments, so screenshot baselines are most useful when those conditions stay consistent.
8. Or skip the browser setup
ScreenshotNeo provides a website screenshot API: one GET request returns an image or PDF. For an ordinary website screenshot, call the API with your URL and API key:
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 API documentation for request options. For a transparent background, use the PNG output option documented by the API; this call is the basic website screenshot example.
ScreenshotNeo accepts cookie and consent banners like a visitor 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, failed loads, timeouts, and cache hits cost nothing, and responses report the page verdict and billing status in headers. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.
Learn about ScreenshotNeo, or sign up free for 1,000 screenshots a month with no card.
9. Frequently asked questions
Does omitBackground make every pixel outside my content transparent?
It hides the browser’s default white background. Any background deliberately painted by the site remains unless you change the page styling.
Can I use this with JPEG?
No. Playwright documents that omitBackground does not apply to JPEG. Use PNG for a transparent screenshot.
Can I capture only a component?
Yes. Take a screenshot from a locator for the target element and pass omitBackground: true.
Does this setting change how the page renders?
It hides the browser’s default background for the screenshot. If you add CSS overrides to remove a site-authored background, those overrides do change the rendered page.
