NewMCP server 1.0.10What changed →

Blog

Puppeteer full-page screenshot, and why images go missing

All posts
guidesscreenshotspuppeteer

A full-page screenshot in Puppeteer is one option: fullPage: true on page.screenshot(). Install Puppeteer, which downloads a matching Chrome, and save this as screenshot.mjs:

bash
npm install puppeteer
javascript
import puppeteer from "puppeteer";

const url = process.argv[2] ?? "https://example.com";

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.setViewport({ width: 1280, height: 800 });
  await page.goto(url, { waitUntil: "networkidle2" });
  await page.screenshot({ path: "page.png", fullPage: true });
} finally {
  await browser.close();
}

Run node screenshot.mjs https://example.com. The image is as wide as the viewport and as tall as the whole document: a test page with twelve 600-pixel sections came out 1280 by 7291 pixels. The try/finally matters once this runs inside a server or a queue worker, where a capture that throws before browser.close() would otherwise leave a Chrome process behind.

Every script here was run with Puppeteer 25.18 against live pages and a small test site built to reproduce the problems below.

Images missing from the bottom of the page

The first full-page screenshot of a real page usually has gaps: empty boxes where images should be, sometimes all of them. Pages load images as they scroll into view, either with loading="lazy" or with a script watching the scroll position, and a full-page screenshot does not scroll. On a test page with 12 lazy-loaded images, seven runs of the script above captured the three nearest the top once and no images at all the other six times. What you get without scrolling depends on timing, which is its own problem.

The fix is to scroll through the page before taking the shot, then wait for the images that scrolling started:

javascript
import puppeteer from "puppeteer";

const url = process.argv[2] ?? "https://example.com";

// Scroll one screen at a time so lazy-loading code sees every section,
// then return to the top so the capture starts where a visitor would.
async function scrollThrough(page) {
  await page.evaluate(async () => {
    const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
    for (let y = 0; y < document.documentElement.scrollHeight; y += window.innerHeight) {
      window.scrollTo(0, y);
      await pause(250);
    }
    window.scrollTo(0, 0);
  });
}

// Resolve once every <img> on the page has finished loading or failed.
async function waitForImages(page) {
  await page.evaluate(() =>
    Promise.all(
      [...document.images]
        .filter((img) => !img.complete)
        .map((img) => new Promise((resolve) => {
          img.addEventListener("load", resolve, { once: true });
          img.addEventListener("error", resolve, { once: true });
        })),
    ),
  );
}

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.setViewport({ width: 1280, height: 800 });
  await page.goto(url, { waitUntil: "networkidle2" });
  await scrollThrough(page);
  await waitForImages(page);
  await page.screenshot({ path: "page.png", fullPage: true });
} finally {
  await browser.close();
}

That captured all 12 images, and still did when each image took 1.5 seconds to arrive. Both halves are needed: scrolling makes the page request the images, and the second function waits for exactly those downloads, so it is not held up by unrelated requests such as analytics, and it does not return while an image is still in flight.

The 250 millisecond pause gives scroll-triggered code a chance to run. Raise it for pages that animate content in as you scroll; lower it for long pages where speed matters more.

Sharper images

Puppeteer captures at one image pixel per CSS pixel unless told otherwise. For a capture that stays crisp on a high-density screen, set a device scale factor:

javascript
await page.setViewport({ width: 1280, height: 800, deviceScaleFactor: 2 });

That doubles both dimensions, so a 1280 by 800 viewport becomes a 2560 by 1600 image, four times the pixels, and a full-page capture grows the same way.

PNG, JPEG or WebP

Puppeteer also writes JPEG and WebP: page.screenshot({ type: "webp", quality: 80 }). Switching to JPEG is the usual advice for long pages, but it does not always pay. Full-page captures of four pages at Puppeteer's default scale, with JPEG and WebP at quality 80:

PagePNGJPEGWebP
Wikipedia, Web scraping (10,596 px tall)1,385 KB2,088 KB1,486 KB
Wikipedia, Example.com358 KB454 KB307 KB
MDN, 429 Too Many Requests428 KB326 KB199 KB
Wikimedia Commons main page, mostly photos701 KB464 KB309 KB

WebP was the smallest on three of the four; on the long, text-heavy article PNG was, and JPEG was larger than PNG on both Wikipedia pages. Text and flat colour compress well losslessly, so measure your own pages before switching.

One element instead of the page

To capture a chart, a pricing table or a single card, take the screenshot from the element:

javascript
const table = await page.waitForSelector("table", { visible: true });
await table.screenshot({ path: "table.png" });

waitForSelector returns the element once it is visible, and the image is cropped to its box.

Still blank, or missing content?

If the screenshot is empty rather than missing images, the page usually was not finished when the screenshot was taken: content fetched after load, a fade-in animation, or a web font still downloading. networkidle2 in particular lets two requests stay open, so it can fire while the request that carries the page's content is still in flight. Five causes of a blank Puppeteer screenshot covers each one with a measured fix.

Without running Chrome

The domscout screenshot API runs the capture on its own Chromium. Set lazyScroll and it scrolls the page in viewport-sized steps, up to 20 of them, before capturing:

javascript
import { writeFile } from "node:fs/promises";

const res = await fetch("https://api.domscout.io/screenshot", {
  method: "POST",
  headers: {
    "x-api-key": process.env.DOMSCOUT_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com",
    fullPage: true,
    lazyScroll: true,
    format: "jpeg",
    quality: 80,
    responseType: "binary",
  }),
});
if (res.status !== 200) throw new Error(`capture failed: ${res.status} ${await res.text()}`);

await writeFile("page.jpg", Buffer.from(await res.arrayBuffer()));

It costs 2 credits: 1 for the capture and 1 for fullPage, which also covers lazyScroll. Full-page capture needs the Pro plan or above, and a page taller than 12,000 pixels is refused with 400 CAPTURE_TOO_TALL rather than cut off silently. A full-page capture with lazyScroll is the heaviest kind of request; if one answers 504, send it again with "async": true and collect it as a job. Try a single page first with the free screenshot tool, no account needed.

Next steps