Transparent Background Screenshots — Capture UI Elements Without White Boxes

You captured a pricing card, a logo, a UI widget. The screenshot looks fine until you drop it onto a slide deck or a marketing page. There's a white rectangle around it. The page background came along for the ride, and now you're in Photoshop removing it pixel by pixel.

The omit_background parameter strips away the default page background and gives you a transparent PNG or WebP. A screenshot transparent background API call, one parameter, and the white box disappears. But there's a catch that trips up almost everyone the first time, and I'll get to that in a moment.

Transparent output in a single request

Add omit_background=true to any screenshot transparent background API request. Chromium skips painting the viewport's default white background, and the result comes back with an alpha channel intact.

curl "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com&selector=.logo&omit_background=true&format=png" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o logo.png

Open that PNG in any image editor and you'll see the checkerboard pattern behind your element. No white box. The logo sits cleanly on whatever background you place it on.

Both format=png and format=webp support transparency. WebP files with alpha channels are typically 25-35% smaller than equivalent PNGs, so if file size matters, try WebP first. For more on image format options, see the format guide.

The background-color trap

Most developers get stuck at this point. You set omit_background=true, run the capture, and the background is still white. The parameter worked. Chromium did remove its default background. But the website's CSS has background-color: #fff on the <body> or <html> element, and that CSS color sits on top of the transparent layer.

The fix takes one extra parameter. ScreenshotRun's css injection lets you override the page styles before the screenshot fires:

curl "https://api.screenshotrun.com/v1/screenshots/capture?url=https://example.com\
&selector=.hero-section\
&omit_background=true\
&css=html, body { background: transparent !important }\
&format=png" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o hero.png

The injected CSS runs before rendering, so Chromium sees a transparent page and a transparent viewport. Your element floats on nothing.

One thing to watch: child elements often have their own background colors. A .card component might have background: white in its own CSS, separate from the body. If you need that card on a transparent background too, include it in the injection: html, body, .card { background: transparent !important }. Target the specific selectors you need. A blanket * { background: transparent } tends to break layouts.

Element screenshots on a clean canvas

The real value shows up when you combine selector with omit_background. Instead of capturing the full page and cropping later, the API grabs just the element you point at. No surrounding content, no page UI, just the component with transparent edges.

// Node.js — capture a pricing card as a transparent WebP
const response = await fetch(
  'https://api.screenshotrun.com/v1/screenshots/capture?' + new URLSearchParams({
    url: 'https://example.com/pricing',
    selector: '.pricing-card',
    omit_background: 'true',
    css: '.pricing-card { background: transparent !important }',
    format: 'webp'
  }),
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const buffer = await response.arrayBuffer();
fs.writeFileSync('pricing-card.webp', Buffer.from(buffer));

This combination works well for design system documentation. Capture each component rendered in a real browser (with real fonts, real CSS, actual responsive behavior) and drop the transparent image straight into your docs site. No Figma export, no stale images when the design changes.

Which formats support transparent PNG and WebP output

Not every image format supports transparency. A quick breakdown by format.

If you pass format=jpeg with omit_background=true, nothing breaks. The API takes the screenshot normally but JPEG has no alpha channel, so the transparent areas appear white. I've seen this confuse developers who test with JPEG first, assume the feature is broken, and open a support ticket. Check your format parameter before debugging anything else.

Where transparent website screenshots show up in production

Device mockups are the most common use case. Marketing teams place screenshots inside phone and laptop frames, and transparent backgrounds let the device frame show through the edges without white bleeding. Tools like Screenhance and Device Shots expect transparent inputs for clean compositing.

Badge and label generation is another one. Generate trust badges, certification marks, or status indicators from HTML templates using the html parameter. The badge renders with real browser typography, and the transparent background means it works on any page color. One API call replaces the manual export step.

Pitch decks work the same way. Drop a UI component screenshot onto a gradient slide. Without transparency, you get a white rectangle. With it, the component sits naturally on the slide background.

Video production teams use transparent PNGs for overlay graphics: data dashboards, live stats widgets, branded lower-thirds. Capture them via the API and composite directly in Premiere or After Effects. The alpha channel handles what a green screen would.

HTML to image transparent background

Transparent backgrounds work with the html and markdown parameters too. You're not limited to capturing existing URLs. For the full HTML to image and Markdown to image workflows, see the dedicated feature pages.

curl -X POST "https://api.screenshotrun.com/v1/screenshots/capture" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<div style=\"padding: 20px; font-family: Inter, sans-serif; font-size: 18px; color: #1a1a1a;\"><strong>Verified</strong> by ScreenshotRun</div>",
    "omit_background": true,
    "format": "webp"
  }'

The response comes back as a WebP with transparent background. Combine this with response_type=base64 and the transparent image stays in memory as a string, ready to embed or pass to another service. Useful for generating badges on the fly inside a serverless function. For details on base64 responses, see Screenshot to Base64.

Puppeteer and Playwright transparent background the hard way

In raw Puppeteer or Playwright, transparent backgrounds require multiple steps: inject CSS to remove the page's own background, then take the screenshot with omitBackground: true. The Puppeteer version looks like this:

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');

// Remove the page's own background color
await page.evaluate(() => {
  document.body.style.background = 'transparent';
  document.documentElement.style.background = 'transparent';
});

// Capture the element with transparent viewport
const element = await page.$('.pricing-card');
await element.screenshot({
  path: 'card.png',
  omitBackground: true
});

await browser.close();

Straightforward on a dev machine. Ship it to production and the requirements multiply: Chromium installation (200+ MB), browser instance management, timeout handling, and memory overhead running into hundreds of megabytes per tab. Firefox-based automation doesn't support omitBackground at all because it requires Chromium's rendering pipeline.

With the screenshot transparent background API, those steps fold into query parameters. No browser to install, no memory to tune.

What this parameter cannot solve

A few limitations worth knowing about before you start:

• CSS injection with background: transparent overrides solid colors. But if the page uses a background image or a gradient on a container inside your target element, you'll need to target that specific container. There's no universal "remove everything" switch for complex backgrounds.
• Elements with backdrop-filter: blur() or rgba() backgrounds produce partial transparency. The alpha values carry through to the output, which can look unexpected if you're compositing onto a very different background color.
• Full-page transparent screenshots are technically possible, but rarely useful. Text and images floating with no background is hard to read. This feature works best for isolated elements and components.

Parameter reference

Pairs well with

Start with a single element. Pick a logo or a UI component from your site, add selector and omit_background=true, and check the output. If the background is still opaque, add the css parameter to force transparency on the element's container. Once that works, the same pattern scales to any component on any page. Complete parameter list in the API docs.