Playwright wait for page to load: reliable waits before screenshots

To make Playwright wait for a page to load, start with page.goto(). Then wait for the content that matters to your task.

For screenshots, that might be a report becoming visible, a chart finishing its render, or the images inside a product card loading. Those events can happen after the browser considers the document loaded.

This guide focuses on those waiting decisions. For viewport settings, element capture, and other screenshot options, see the broader guide on how to render screenshots with Playwright.

Quick example: wait before taking a screenshot

Install Playwright and its Chromium browser:

1
npm install playwright
2
npx playwright install chromium

Save this as screenshot.mjs and run it with node screenshot.mjs:

1
import { chromium } from "playwright";
2

3
const browser = await chromium.launch();
4

5
try {
6
    const page = await browser.newPage({
7
        viewport: { width: 1280, height: 800 },
8
    });
9

10
    await page.goto("https://example.com", {
11
        waitUntil: "domcontentloaded",
12
        timeout: 30_000,
13
    });
14

15
    await page.getByRole("heading", { name: "Example Domain" }).waitFor({
16
        state: "visible",
17
        timeout: 10_000,
18
    });
19

20
    await page.evaluate(async () => {
21
        await document.fonts.ready;
22
    });
23

24
    await page.screenshot({
25
        path: "screenshot.png",
26
        fullPage: true,
27
        animations: "disabled",
28
        caret: "hide",
29
    });
30
} finally {
31
    await browser.close();
32
}

The heading is a useful readiness signal for this simple page. On your own application, replace it with a signal that appears when the desired content is ready, such as a completed report or a populated results table.

animations: "disabled" handles CSS animations, CSS transitions, and Web Animations. It does not freeze every JavaScript animation, canvas, or video on a page. See Playwright’s screenshot options.

Which wait should you use?

Choose the wait based on the event you expect. A browser event, a network response, and a visible report each answer a different question.

page.goto and waitUntil

Without options, page.goto(url) waits for the load event:

1
await page.goto("https://example.com");

You can choose a different navigation milestone with waitUntil:

These are document lifecycle milestones. They do not describe every asynchronous update inside an application.

For example, a page can load its HTML and then request the data for a chart. The screenshot should wait for the chart’s completed state, even if load has already fired.

Wait for a selector or locator

For dynamic content, a locator is often the clearest option:

1
await page.goto("https://example.com/report", {
2
    waitUntil: "domcontentloaded",
3
});
4

5
await page.locator('.report[data-ready="true"]').waitFor({
6
    state: "visible",
7
    timeout: 30_000,
8
});
9

10
await page.screenshot({ path: "report.png", fullPage: true });

Here, data-ready="true" is an example of a signal your application provides after it has rendered the report. Replace the URL and selector with those from your site.

Waiting for an empty report container is weaker: the container might exist before any data arrives. A spinner disappearing, a result count appearing, or an application-provided ready attribute can be more useful.

For new code, Playwright recommends locator-based waits. page.waitForSelector() still exists, but locators fit better with the rest of Playwright’s API.

What Playwright auto-waiting covers

Before actions such as locator.click(), Playwright checks whether the target is actionable. That can include whether it is visible, stable, enabled, and able to receive events. See the auto-waiting documentation.

That helps you interact with a page. It does not tell Playwright which business state you want to capture afterward.

For example, a button can be ready to click while the report it generates still takes another second to render:

1
await page.getByRole("button", { name: "Generate report" }).click();
2

3
await page.locator('.report[data-ready="true"]').waitFor({
4
    state: "visible",
5
});

For tests, Playwright’s retrying assertions are another useful choice. For a standalone screenshot script, a locator wait gives you a straightforward readiness check without adding a test runner.

Wait for navigation after a click

Start waiting for the destination as part of the action that triggers navigation:

1
await Promise.all([
2
    page.waitForURL("**/dashboard", {
3
        waitUntil: "domcontentloaded",
4
        timeout: 30_000,
5
    }),
6
    page.getByRole("link", { name: "Dashboard" }).click(),
7
]);
8

9
await page.locator('[data-dashboard-ready="true"]').waitFor({
10
    state: "visible",
11
});

The URL establishes that you reached the destination. The locator establishes that its content is ready.

Playwright deprecates page.waitForNavigation() and recommends page.waitForURL(). Its navigation guide also explains why page load and application readiness can differ.

If your code is failing during redirects or page.evaluate(), see how to fix the Playwright execution context error.

Wait for an API response and then the rendered result

If a button fetches data without changing the URL, register a response wait before clicking:

1
const reportResponse = page.waitForResponse(
2
    (response) =>
3
        response.url().endsWith("/api/report") &&
4
        response.request().method() === "GET" &&
5
        response.ok(),
6
    { timeout: 30_000 }
7
);
8

9
await page.getByRole("button", { name: "Load report" }).click();
10
await reportResponse;
11

12
await page.locator('.report[data-ready="true"]').waitFor({
13
    state: "visible",
14
});

Adjust the URL predicate to match your application. For repeated loads, make the readiness signal identify the new result, rather than an earlier report already on the page.

A successful response means the data arrived. Rendering may still happen afterward, which is why the example also waits for the completed report.

Wait for fonts and images

Once the desired content exists, wait for fonts before capturing text:

1
await page.evaluate(async () => {
2
    await document.fonts.ready;
3
});

For images inside a known section, you can add a bounded check:

1
await page.locator(".report").waitFor({ state: "visible" });
2

3
await page.waitForFunction(
4
    () =>
5
        Array.from(document.querySelectorAll(".report img")).every(
6
            (image) => image.complete && image.naturalWidth > 0
7
        ),
8
    null,
9
    { timeout: 10_000 }
10
);

This checks image elements in the report, not CSS background images. A broken image will cause a timeout, which is useful when a missing image should fail the capture.

Lazy-loaded images below the viewport may not have been requested yet. Scroll the relevant content into view before checking it. Setting fullPage: true alone does not perform the scrolling needed to trigger every lazy-loading implementation.

For long pages, see the full-page screenshot guide.

When waitForLoadState is useful

Use page.waitForLoadState("load") when the current page has begun navigation and you need to wait for that document event.

After this code, a second load wait is usually redundant:

1
await page.goto("https://example.com");
2
await page.waitForLoadState("load");

goto() already waited for load. Calling waitForLoadState() again does not restart loading or wait for a later React update.

Why networkidle and fixed delays can disappoint

A page can keep making background requests long after its useful content appears. Conversely, the network can become quiet before a timer or client-side computation updates the page.

That makes networkidle a poor universal definition of screenshot readiness. Playwright explicitly discourages it as a readiness check for tests in its load-state documentation.

A fixed delay has a similar trade-off:

1
await page.waitForTimeout(5000);

Five seconds can be too short on a slow page and unnecessarily long on a fast one. Use it while diagnosing a timing issue, or as a measured fallback when a third-party page has no useful readiness signal. Prefer an observable condition when one exists.

The same approach in Python

Install the Python package and browser:

1
python -m pip install playwright
2
python -m playwright install chromium

Then use wait_until for navigation and a locator for content readiness:

1
from playwright.sync_api import sync_playwright
2

3
with sync_playwright() as playwright:
4
    browser = playwright.chromium.launch()
5
    try:
6
        page = browser.new_page(viewport={"width": 1280, "height": 800})
7
        page.goto("https://example.com", wait_until="domcontentloaded")
8
        page.get_by_role("heading", name="Example Domain").wait_for(
9
            state="visible", timeout=10_000
10
        )
11
        page.evaluate("async () => { await document.fonts.ready; }")
12
        page.screenshot(path="screenshot.png", full_page=True)
13
    finally:
14
        browser.close()

The Python Playwright screenshot guide covers more output and browser options.

Use ScreenshotOne for managed screenshot rendering

If your application needs website screenshots, ScreenshotOne gives you rendering controls through an HTTP API. You can set a load event, wait for a selector, block cookie banners, and capture a full page without running Playwright in your application.

1
curl --fail-with-body --get "https://api.screenshotone.com/take" \
2
    --data-urlencode "access_key=YOUR_ACCESS_KEY" \
3
    --data-urlencode "url=https://example.com" \
4
    --data-urlencode "wait_until=load" \
5
    --data-urlencode "full_page=true" \
6
    --data-urlencode "block_cookie_banners=true" \
7
    --data-urlencode "block_ads=true" \
8
    --output screenshot.png

For a dynamic page, add --data-urlencode 'wait_for_selector=.report[data-ready="true"]' with your own selector. ScreenshotOne’s selector wait checks for DOM presence, so choose a selector whose presence represents the finished content. It is not equivalent to Playwright’s visible locator wait.

See the ScreenshotOne wait options and full-page rendering options. You can also compare the approaches in ScreenshotOne vs ScrapingBee for screenshots.

Frequently Asked Questions

If you read the article, but still have questions. Please, check the most frequently asked. And if you still have questions, feel free reach out at support@screenshotone.com.

How do I wait for a page to load in Playwright?

Use page.goto(url) for initial navigation. It waits for the load event by default. For a JavaScript application, also wait for the element or application state you need before reading content or taking a screenshot.

Should I use networkidle before every Playwright screenshot?

No. Network silence does not guarantee that the content you need has rendered. Prefer a visible locator or a specific readiness condition. Playwright also discourages using networkidle as a general readiness check for tests.

Does waitForLoadState wait for React or Vue to finish rendering?

No. It waits for a document lifecycle event. A React or Vue application can update after that event, so wait for a ready element, response, or application-specific condition as well.