scalpel@labs: ~/glossary/css-background-image.mdx5 sections

CSS background-image

A CSS background-image paints a picture behind an element through a stylesheet rule, not an img tag. The URL lives in the element's computed style, so the only reliable way to find these is to sweep getComputedStyle across the page, which is how Scalpel Images catches them.

extension: Scalpel Imagesupdated: 2026-08-14read_time: 2 min
less css-background-image.mdx

Why it matters

Hero banners, gallery thumbnails and icon sets are painted by CSS background-image far more often than you'd expect. Right-click "save image" does nothing on them: the browser sees only the element, not the image beneath it. Most bulk downloaders scan the DOM for <img> tags and miss entire galleries.

Reading computed styles is the one method that finds them wherever they hide. If you want to keep every image on a page, you cannot skip the background layer.

How it works

An element gets a background image through CSS: background-image: url('/photo.jpg'). This URL lives in the CSS rule, not the HTML. The only way to read it is to call window.getComputedStyle() on every element and extract the background-image value from its computed style.

Scalpel Images walks the DOM, computes the style for each element, parses the url() value, and resolves relative URLs against the page's base. It also handles multiple url() values in a single background-image declaration (comma-separated fallbacks for older browsers).

Gradients like linear-gradient(red, blue) carry no file, so they're correctly ignored. Pseudo-element backgrounds from ::before and ::after are harder to extract without rendering the pseudo-element's DOM (which browser automation APIs can do, but at cost). The extension skips these by design to keep the scan fast.

What does not matter

The display size of the element does not matter. A 50px box with a 2000px background image still holds the full-resolution file. And the background-image style does not have to come from the element's own class. It might be inherited from a parent or set by a media query. getComputedStyle reports the final, resolved value regardless of where it came from.

Also, CSS can combine background-image with background-position, background-size and other properties. The image URL is what matters for extraction; the rest is just how the browser paints it.

Code example

/* In your stylesheet */
.hero {
  background-image: url('/banner.jpg');
  background-size: cover;
  background-position: center;
}

To extract the URL, you'd read it this way:

const element = document.querySelector('.hero');
const style = window.getComputedStyle(element);
const backgroundImage = style.backgroundImage;
// → "url("https://example.com/banner.jpg")"

// Then parse the URL out of the string
const urlMatch = backgroundImage.match(/url\(["']?([^"']*)\1?["']?\)/);
if (urlMatch) {
  const imageUrl = urlMatch[1];
  console.log(imageUrl);
  // → "https://example.com/banner.jpg"
}

How Scalpel Images shows it

When Scalpel Images scans a page, every picture found via CSS background-image carries a BG (background) badge on its tile. You can filter by source using the background chip at the top to see only these images, and they download through the same naming pipeline as any other image on the page.

Sources