The format has no alpha channel
JPEG cannot store transparency at all, and asking for it there is not a partial result — the transparent area is filled with whatever the encoder decides, usually white or black.
01 · Diagnose the problem
Why a transparent background arrives white, and how to keep the alpha
A browser window is not transparent. Even when every element in the document declares a transparent background, the renderer paints an opaque canvas underneath before it paints anything of yours — so an image captured from it is opaque unless the capture explicitly asks otherwise.
4 min readPublished Updated
What you actually see
A logo, badge or card exported for use over an unknown background arrives with a white rectangle around it, and the CSS inspector insists the background is transparent.
Reproduce it
- 01Capture the element twice, once with the renderer asked to omit the background and once without, and compare the two files in a viewer that shows a checkerboard rather than white.
- 02Run
getComputedStyle(document.body).backgroundColorin the page: a CSS reset or a framework base layer often sets it to an opaque value that no rule of yours mentions. - 03Convert the result to JPEG and back: if the transparency was still there, this is where it stops being there.
02 / Do it yourself
Ask the renderer not to paint a canvas
Clear the background on the document as well as on the element, ask the renderer to skip its own canvas, and write to a format that has an alpha channel.
transparent.mts
await page.setContent(card, { waitUntil: "load" });
// The document, not only the element: a reset stylesheet is the usual culprit.
await page.addStyleTag({ content: "html,body{background:transparent!important}" });
const opaque = await page.evaluate(() => getComputedStyle(document.body).backgroundColor);
if (opaque !== "rgba(0, 0, 0, 0)") throw new Error(`body still paints ${opaque}`);
await page.locator("#card").screenshot({
path: "card.png", // png, not jpeg: the format has to be able to hold alpha
omitBackground: true, // without this the renderer paints white underneath
});03 / Where it breaks
The three layers that can repaint it anyway
The call above is small. Everything around it is the system — and the system is what you would be signing up to own.
A reset stylesheet paints the document
Normalize and most framework base layers set an opaque background on body. Your element being transparent does not help when the surface behind it is not.
Something later flattens it
A thumbnailer, an email client or an image pipeline that re-encodes to JPEG removes the alpha after you produced it correctly. The failure is downstream of the capture.
The viewer lies to you
Many previews composite transparency onto white, so a correct file and a broken one look identical until you open it over a checkerboard or a coloured surface.
Keep the DIY version when
- The artifact will always sit on a known, fixed colour — painting that colour into the image is simpler and produces a smaller file.
- The output is a photograph or a full-page screenshot, where there is no transparent region to preserve in the first place.
05 / Output, limits, cost, failures
What a capture with alpha actually returns
Output
A PNG whose transparent regions are genuinely empty, so the artifact composites over any background instead of carrying a rectangle of its own.
Cost
One successful, non-cached capture costs one credit. Failures, including platform failures, cost zero; cache hits cost zero.
1 creditper successful non-cached capture
Limits
- Only formats with an alpha channel can hold the result; the request is refused rather than silently flattened when the format cannot.
- Transparency costs bytes: a lossless format is the price of an alpha channel, and a photographic card is much cheaper without one.
- Nothing downstream is under our control — a pipeline that re-encodes the file can still remove what the capture preserved.
Common errors
request_not_validnever billed
The requested format has no alpha channel and the request asks for the background to be omitted.
HTTP 400 · terminal
request_body_too_largenever billed
The inline markup embeds large data URLs and the body passes the limit.
HTTP 413 · terminal
06 / Take it for a run
Try it against your own page
Swap the example for a page you care about. The runner keeps every option from this guide, and carries the whole configuration into the playground — no retyping, no starting over.
07 / Verification
Tested and reviewedWritten by PageCapture Engineering. Reviewed by PageCapture render maintainers. Verified 2026-08-26 by running the published code against a fixture.
The recipe was normalized through the public contract and its markup rendered with the pinned Chromium build, with and without the omitted background; the CI fixture run has not executed this piece yet.
Sources and verification basis
Sources support the browser and API behaviors named above. PageCapture-specific limits and billing are taken from the public contract; external sources are used for the underlying browser behavior.
Defines alpha compositing and the transparent keyword this guide relies on.
- Page.screenshotPlaywright
Documents the omitBackground option used by the DIY fix.
08 / Continue from here
Related guides and reference
Try it without an account
The same two halves of the fix as a form: PNG output and the background left off.
The option itself
Type, default and which formats accept it, straight from the parameter contract.
What the alpha costs
Keeping transparency forces a lossless format, and that decision has a price in bytes.
Image options
Every encoding parameter next to the one this guide turns on.