Puppeteer waitUntil: When Is a Page Ready to Screenshot?

waitUntil decides when page.goto() returns, not when your page is ready. For a screenshot you usually want three separate things: the navigation to finish, the content you care about to render, and the fonts and images inside the frame to paint. This is the pattern that captured a complete page on every run in our tests:

await page.goto(url, { waitUntil: 'load' });
await page.waitForSelector('#chart', { visible: true });
await page.screenshot({ path: 'page.png' });

The rest of this post shows why, with timings from a test SPA, and gives you a reusable waitUntilReady() helper. It is part of our Puppeteer screenshot guide.

Tested with: Puppeteer 25.14.0, Chrome 155.0.8059.79 (the browser Puppeteer downloads), Node.js 22.18.0, macOS on an Apple M1 Pro. Tested on 2026-10-18.

The six options in one table

You can pass an array to waitUntil, for example ['load', 'networkidle2']. goto() then resolves when all of them have happened.

What we measured

We built a small single-page app and served it from a local Node.js server, so network timing is the same on every run. The page:

1. Opens a long-poll request (/poll) that the server holds for 10 seconds. This stands in for chat widgets, analytics and live-update connections.
2. After 300 ms, fetches /api/orders. The server answers after 800 ms, and the page renders 20 rows into #content.
3. 700 ms after the rows, draws #chart with no network request (like a charting library that animates in), then sets window.__ready = true.

A capture is complete only if all 20 rows and the chart are in the DOM when the screenshot is taken. Each strategy ran 5 times, each in a fresh browser context; the time covers goto plus the wait plus page.screenshot().

What the numbers say:

• load and domcontentloaded are fast and wrong for client-rendered pages. Both returned before the data request even started, so every screenshot showed "Loading…".
• networkidle2 returned before the data arrived. With the long-poll open (one connection), the page went "almost idle" during the 300 ms pause before fetch('/api/orders'). A short gap between requests is all it takes.
• networkidle0 was correct but took 12 seconds, because it had to wait for the 10-second long-poll to close. On a real site with a chat widget, it may never resolve.
• Waiting for the wrong selector is the same as not waiting. #content li appeared 700 ms before the chart, so the capture had rows but no chart. Pick the element that renders last.
• A selector or function for the last thing to render was correct and fast, at about 1.9 seconds, which is roughly the real render time of the page.

For contrast, we also timed goto() alone on https://example.com (3 runs each, over the internet): domcontentloaded 269 to 445 ms, load 228 to 438 ms, networkidle2 959 to 999 ms, networkidle0 980 to 997 ms. On a static page the network-idle options cost you about half a second of pure waiting and buy nothing.

A trap we found: unread response bodies

The first version of our test page started the long-poll with fetch('/poll').catch(() => {}) and never read the response. With that page, networkidle0 never resolved. It hit the 60-second timeout even though the server answered after 10 seconds.

Puppeteer's requestfinished event never fired for /poll, so the request counted as open. When we changed the page to fetch('/poll').then((r) => r.text()), networkidle0 resolved about 2 seconds after the poll ended. You cannot fix someone else's page, but this explains a class of "networkidle0 times out on one site only" reports: the page is not busy, it just never consumed a response.

Recipes

Server-rendered pages

If the HTML arrives complete from the server (most marketing sites, docs, blogs), load is enough. Add a font check, because load does not wait for fonts that CSS requests late:

await page.goto(url, { waitUntil: 'load' });
await page.evaluate(() => document.fonts.ready);

Client-rendered pages (React, Vue, Svelte)

Wait for the element that renders last and make it visible-only, so an empty placeholder does not count:

await page.goto(url, { waitUntil: 'load' });
await page.waitForSelector('[data-testid="revenue-chart"] svg', { visible: true, timeout: 15_000 });

If a skeleton loader is easier to target than the content, wait for it to go away instead:

await page.waitForSelector('.skeleton', { hidden: true });

Pages you control: a ready flag

When you own the page (an OG card template, an internal dashboard), have it announce readiness. This is the most reliable option because the page knows when its own work is done:

// In your page, after the last render:
window.__ready = true;

// In Puppeteer:
await page.waitForFunction(() => window.__ready === true, { timeout: 10_000 });

Locators

Puppeteer locators retry until the element is attached, visible and stable, so they double as a wait:

const chart = await page.locator('#chart').waitHandle();
await chart.screenshot({ path: 'chart.png' });

See element screenshots in Puppeteer for padding, shadow DOM and transparent backgrounds.

A fixed delay, if you must

page.waitForTimeout() was removed in Puppeteer 22. A fixed pause is a last resort for CSS animations with no end event:

await new Promise((resolve) => setTimeout(resolve, 600));

Prefer turning animations off: await page.emulateMediaFeatures([{ name: 'prefers-reduced-motion', value: 'reduce' }]) works on pages that respect the setting.

A reusable waitUntilReady() helper

This helper combines the parts that worked: a content check, a short network quiet that is allowed to time out, fonts, decoded images in the viewport, and two animation frames so the last style change is painted. It is a complete script.

import puppeteer, { TimeoutError } from 'puppeteer';

/**
 * Wait until a page is ready to screenshot.
 * readySelector: an element that only exists once the data has rendered.
 */
export async function waitUntilReady(page, { readySelector, quietMs = 500, maxQuietWaitMs = 3_000 } = {}) {
  // 1. The content you care about is on screen.
  if (readySelector) {
    await page.waitForSelector(readySelector, { visible: true, timeout: 15_000 });
  }

  // 2. Short, bounded network quiet. Two open connections are allowed
  //    (long-polls, analytics); a page that never goes quiet is not an error.
  try {
    await page.waitForNetworkIdle({ idleTime: quietMs, concurrency: 2, timeout: maxQuietWaitMs });
  } catch (err) {
    if (!(err instanceof TimeoutError)) throw err;
  }

  // 3. Web fonts are loaded and images in the viewport are decoded.
  await page.evaluate(async () => {
    await document.fonts.ready;
    const inView = [...document.images].filter((img) => {
      const r = img.getBoundingClientRect();
      return r.bottom > 0 && r.top < innerHeight && img.src;
    });
    await Promise.all(inView.map((img) => img.decode().catch(() => {})));
  });

  // 4. Two animation frames, so the last style change is painted.
  await page.evaluate(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))));
}

const [url = 'https://example.com', readySelector] = process.argv.slice(2);
const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.setViewport({ width: 1280, height: 800 });
  const t0 = performance.now();
  await page.goto(url, { waitUntil: 'load', timeout: 30_000 });
  await waitUntilReady(page, { readySelector });
  await page.screenshot({ path: 'ready.png' });
  console.log(`ready in ${Math.round(performance.now() - t0)} ms`);
} catch (err) {
  console.error(err);
  process.exitCode = 1;
} finally {
  await browser.close();
}

Run it with node ready.mjs <url> [selector]. Results on our machine:

Two things to note. Without a selector, the bounded network quiet is not enough on its own for a client-rendered page, which matches the networkidle2 row above. And the helper takes about 500 ms longer than the bare selector wait, which is the price of the network quiet and the font and image checks. Drop step 2 when you know the page has no late requests.

One more lesson: we first tried h1 as the selector for example.com, and it timed out. The page currently has no <h1>. Check your selector against the live page, not your memory of it.

Timeouts: set three, not one

A single global timeout hides which stage failed, and a bare "Navigation timeout of 30000 ms exceeded" does not say why. Give each stage its own budget so the error tells you what went wrong:

page.setDefaultNavigationTimeout(30_000);                    // goto
await page.waitForSelector('#chart', { timeout: 15_000 });    // content
await page.waitForNetworkIdle({ idleTime: 500, timeout: 3_000 }).catch(() => {}); // optional quiet

If you capture many pages in one process, read Puppeteer timeouts and memory leaks next: a stuck wait that never closes its page is the usual start of a memory leak.

Troubleshooting

The same wait with one API call

RenderScreenshot exposes the same choices as request parameters (see wait options): wait.until accepts load, domcontentloaded or networkidle; wait.for_selector waits for an element with a mode of visible, hidden, attached or detached; wait.delay adds a pause after the condition, and wait.timeout caps the total in seconds (max 60).

import { writeFile } from 'node:fs/promises';
import { Client, TakeOptions } from 'renderscreenshot';

const client = new Client(process.env.RS_API_KEY);

const image = await client.take(
  TakeOptions.url('https://example.com/dashboard')
    .waitFor('load')
    .waitForSelector('#chart')
    .waitForTimeout(30)
);
await writeFile('dashboard.png', image);

The browser, timeouts and retries run on our side. Our wait strategies guide covers which option fits which kind of page. You can try it with the 150 free credits each month on the free plan.

Related guides

• Taking screenshots with Puppeteer, the hub for this series
• Playwright wait for page load, the same question with Playwright's auto-waiting
• Puppeteer request blocking, to remove the trackers that keep the network busy
• Scaling Puppeteer screenshots, for running these waits in parallel