Skip to content

How to Wait for Page to Load in Playwright

Playwright does not wait for every asynchronous request that fires after the first page load.

OUTPUT FORMATSHTMLJSONMarkdown

If the data you need arrives later, you have to tell Playwright what to wait for. The four approaches below cover the common cases: a specific element, an implicit locator wait, a browser load state, or a fixed delay. Use them in that order of preference unless the page gives you a reason to do otherwise.

Quick decision: which Playwright wait should you use?

Start with the most specific signal the page can give you. A selector that only appears once the content is ready is usually the most reliable choice. Playwright's auto-waiting handles element interactions without an explicit wait, but it does not cover data that loads after the initial page load. Use a load state when you need to know the browser has finished a phase of loading. Reserve fixed timeouts for pages that offer no reliable selector, load state, or network response to wait on.

1. Wait for a selector before reading the page

The wait_for_selector method pauses until a matching element appears, which is useful when the HTML you need is injected after the initial response. The example below opens a Pinterest search for sneakers, waits for the pin grid to appear, and then saves a screenshot. Install Playwright and its browser binaries first.

2. Let Playwright auto-wait on a locator

Locators carry built-in waiting. When you call locator.wait_for(), Playwright waits for that element to be ready before the next action. If the element never appears within the timeout, Playwright raises a timeout error. The example below waits for the Pinterest search feed and then retrieves the page HTML.

3. Use a fixed timeout only as a fallback

page.wait_for_timeout pauses for a number of milliseconds. It is simple, but it is also the least dependable option: a short delay may fire before the page is ready, and a long delay slows every run. Reach for it only when the page exposes no reliable selector, load state, or network response. The example below waits ten seconds before taking a screenshot.

4. Wait on network activity

page.wait_for_load_state('networkidle') waits until network requests triggered by the page load have settled. It can also be used after a scroll or click to wait for new data. Be careful: pages with polling, ads, or analytics may never go idle, and the call will run until it times out. Playwright's own documentation discourages networkidle for this reason. If that risk applies, use a selector or one of the other methods instead. You can also wait for the load or domcontentloaded load state, or use wait_for_request() and wait_for_response() when a specific request or response is the signal you need.

Failure distinction: timeout from a missing selector vs. a network that never idles

A timeout error from locator.wait_for() or wait_for_selector usually means the element you expected never appeared, so check the selector and whether the content actually loaded. A timeout from wait_for_load_state('networkidle') often means the opposite: the page is still busy with polling, ads, or analytics and will not settle. In that case, switch to a selector-based wait or a specific request/response wait rather than increasing the timeout.

Reader checklist before choosing a wait

  1. Does the page expose an element that only appears when the data is ready? Prefer wait_for_selector or locator.wait_for(). 2. Are you interacting with an element rather than reading raw HTML? Playwright's auto-waiting may already cover it. 3. Do you need a browser load phase? Use wait_for_load_state with load or domcontentloaded. 4. Does the page keep polling, show ads, or run analytics? Avoid networkidle. 5. Is there a specific request or response that marks readiness? Use wait_for_request() or wait_for_response(). 6. Only if none of the above applies, use page.wait_for_timeout as a fallback.
Playwright wait methods at a glance
MethodWhat it waits forBest forMain risk
page.wait_for_selector()A matching element to appearContent injected after initial loadSelector may be wrong or content may never load
locator.wait_for()A specific locator to be readyInteracting with or reading a known elementTimeout if the element never appears
page.wait_for_load_state('networkidle')Network requests to settlePages that finish loading cleanlyPolling, ads, or analytics may prevent idle
page.wait_for_load_state('load' / 'domcontentloaded')A browser load phaseWaiting for the document or full loadDoes not cover later AJAX data
page.wait_for_timeout()A fixed number of millisecondsPages with no reliable signalSlow runs or premature reads
page.wait_for_request() / page.wait_for_response()A specific network request or responseWaiting on a known API callRequires knowing the request or response

This table summarizes the methods described in the accompanying code examples. It is not a claim that every method works on every site.

Frequently asked questions

Why doesn't Playwright wait for my AJAX content automatically?

Playwright waits for navigation and many page interactions, but it does not wait for asynchronous XHR or AJAX requests that run after the initial page load. If your data arrives later, wait for an element that confirms the content is ready before parsing the page.

When should I avoid wait_for_load_state('networkidle')?

Avoid it on pages with polling, ads, or analytics, because the network may never become idle and the call will run until it times out. Playwright's own documentation discourages networkidle for this reason. Use a selector-based wait or a specific request/response wait instead.

What is the difference between wait_for_selector and locator.wait_for()?

wait_for_selector is a page-level method that waits for a selector to appear. locator.wait_for() waits on a specific locator and is part of Playwright's auto-waiting behavior. Both raise a timeout error if the element does not appear in time.

Can I wait for a specific network request instead of the whole page?

Yes. Playwright provides wait_for_request() and wait_for_response() when you need to wait for a particular request or response rather than a load state.