How to Wait for Page to Load in Playwright
Playwright does not wait for every asynchronous request that fires after the first page load.
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
- 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.
| Method | What it waits for | Best for | Main risk |
|---|---|---|---|
| page.wait_for_selector() | A matching element to appear | Content injected after initial load | Selector may be wrong or content may never load |
| locator.wait_for() | A specific locator to be ready | Interacting with or reading a known element | Timeout if the element never appears |
| page.wait_for_load_state('networkidle') | Network requests to settle | Pages that finish loading cleanly | Polling, ads, or analytics may prevent idle |
| page.wait_for_load_state('load' / 'domcontentloaded') | A browser load phase | Waiting for the document or full load | Does not cover later AJAX data |
| page.wait_for_timeout() | A fixed number of milliseconds | Pages with no reliable signal | Slow runs or premature reads |
| page.wait_for_request() / page.wait_for_response() | A specific network request or response | Waiting on a known API call | Requires 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.