How to wait for page to load in Puppeteer?
Puppeteer scripts often need to pause until a page has finished rendering the content they want to read.
The most direct approach is to wait for a specific element with waitForSelector. This guide explains that method, shows a sample using a five-second timeout, and helps you decide when a selector wait is enough and when you need a different navigation check.
Wait for a specific element with waitForSelector
The waitForSelector method pauses execution until the selector you provide matches an element on the page. That makes it a practical signal that the content you intend to scrape has appeared, especially on dynamic sites where the initial HTML does not contain the final content. The method accepts a selector and an options object; the sample below sets a timeout of 5,000 milliseconds. If the element does not appear within that window, the wait fails and you can decide whether to retry, extend the timeout, or inspect the selector.
Sample: open a page and wait for the content section
The captured sample launches a browser, opens a new page, navigates to the site base URL, and waits for the #content selector. The URL is an owner-controlled placeholder, so replace it with the page you actually need to load. The timeout is set to 5,000 milliseconds. After the wait resolves, the script can continue with whatever extraction or interaction step comes next.
Decision checklist: which wait should you use?
Use this checklist to pick a wait strategy before you add more code:
- Does the page render the target content after the initial document load? If yes, a selector wait is usually the simplest signal.
- Do you know a stable selector for the content you need? If yes, waitForSelector gives you a clear success condition.
- Is the selector likely to appear only after a network request or a client-side render? If yes, allow enough time and consider whether a navigation-level wait is more appropriate.
- Does the page have no single stable element to watch? If yes, a selector wait may be fragile, and you should look at navigation options or a broader readiness check.
- Is the timeout shorter than the slowest realistic render? If yes, increase it or add a retry path so a slow page does not fail the run.
Missing element versus timeout: a useful distinction
A waitForSelector failure can mean two different things. First, the selector may be wrong or may never match because the page structure changed. Second, the selector may be correct but the page did not render it within the timeout window. The first case calls for inspecting the page and updating the selector. The second calls for checking network conditions, increasing the timeout, or waiting on a different signal. Separating these cases prevents you from repeatedly extending a timeout when the real problem is a stale selector.
Puppeteer web scraping tutorial
For a broader walkthrough of web scraping with Puppeteer, see the linked tutorial in the source registry.
Frequently asked questions
What happens if waitForSelector times out?
The wait rejects with a timeout error. That can mean the selector is wrong, the element never rendered, or the page was slower than the configured timeout. Check the selector first, then consider a longer timeout or a different readiness signal.
Is waitForSelector the only way to wait for a page to load in Puppeteer?
No. waitForSelector is a practical element-level signal, but Puppeteer also offers navigation options and other checks. The right choice depends on whether you know a stable selector for the content you need and whether the page finishes rendering after the initial navigation.