How to Wait for a Target in Puppeteer

Direct answer: “Target” can mean three different things in Puppeteer. Use page.waitForSelector() for a DOM element, page.waitForFunction() for a custom condition in the page, and browserContext.waitForTarget() for a browser target such as a popup. If you are waiting so you can click or fill an element, a Puppeteer locator usually handles the wait and action preconditions for you.

A Puppeteer browser Target is not the same thing as an HTML element. Pick the API based on what you expect to appear or become true.

1. Choose the wait that matches your target

What you are waiting for	Use	Example
An element in the DOM	page.waitForSelector()	A submit button is inserted or becomes visible.
A page condition	page.waitForFunction()	A result count becomes nonzero or a global flag is set.
A popup or other browser target	browserContext.waitForTarget()	A link opens a report in a new page.
An element you will interact with	page.locator()	Click a button and let Puppeteer wait for its action preconditions.

The examples below use JavaScript with Node.js and Puppeteer. They assume a page has already been opened. Ensure your installed Puppeteer version matches the API documentation you consult; wait APIs and options can vary by release.

2. Wait for a DOM element

waitForSelector resolves immediately if the selector already matches. Otherwise it waits for the element to be added to the DOM. The default timeout documented for this API is 30,000 milliseconds.

const button = await page.waitForSelector('button.submit', {
  visible: true,
  timeout: 10_000,
});

if (button) {
  try {
    await button.click();
  } finally {
    await button.dispose();
  }
}

visible: true waits for the element to exist and not be hidden by display: none or visibility: hidden. It does not guarantee that an overlay will not intercept a click or that the element is otherwise ready for your application’s workflow.

Use hidden: true to wait for an element to become hidden or absent. If it is absent from the DOM, the wait resolves to null. Do not set both visible and hidden to true as a way to express a single condition; choose the state you actually need.

await page.waitForSelector('.loading-spinner', {
  hidden: true,
  timeout: 15_000,
});

The timeout option controls how long this specific wait may take. A timeout of 0 disables the timeout, which can leave an automation run waiting indefinitely. You can change the default for page waits with page.setDefaultTimeout(milliseconds). A supported signal option can cancel a wait; check the documentation for the installed Puppeteer release.

3. Wait for a custom page condition

Use waitForFunction when readiness is more than the presence of one selector. Puppeteer evaluates the function in the page context until it returns a truthy value. Pass data from Node.js as arguments rather than interpolating it into function source.

await page.waitForFunction(
  selector => {
    const element = document.querySelector(selector);
    return element && element.textContent.trim().length > 0;
  },
  { timeout: 10_000 },
  '.results-loaded',
);

The predicate runs in the browser page, so it can use page APIs such as document, but it cannot directly access Node.js variables unless you pass them as arguments. Return a boolean or another value that becomes truthy only when the desired state is reached. Keep the predicate focused and inexpensive because Puppeteer evaluates it repeatedly while waiting.

4. Wait for a popup or browser Target

For a new page created by window.open or a similar action, wait on the browser context. Start the wait before clicking the control that creates the target so the wait is already listening.

const context = page.browserContext();
const targetPromise = context.waitForTarget(
  target => target.url() === 'https://example.com/report',
  { timeout: 10_000 },
);

await page.click('a.open-report');
const target = await targetPromise;
const popup = await target.page();

if (!popup) {
  throw new Error('The matching target is not a page');
}

await popup.waitForSelector('main.report', { visible: true });

The predicate receives a Puppeteer Target. Match a distinguishing property such as a specific URL; a broad predicate can resolve on an unrelated page, worker, or other target. If the popup URL redirects, match a stable URL prefix or another identifying property appropriate to the flow. target.page() can return null for targets that are not pages, so handle that case.

5. Prefer locators for element interactions

If the only reason to wait is to click, type, or otherwise interact with an element, use a locator where it fits. Puppeteer documents locators as its recommended interaction approach; they automatically wait for the element and action preconditions.

await page.locator('button.submit').click();

Use waitForSelector when you need lower-level access to an ElementHandle, such as reading properties or passing a handle to another API. Dispose of a handle when finished, especially in long-running automation, to avoid retaining resources longer than necessary. For page and frame waits, prefer the page or frame scope if navigation may replace the document. An ElementHandle.waitForSelector() is tied to that element and does not work across navigation or after the element is detached.

6. Handle navigation and timing carefully

Frame.waitForSelector() is documented to work across navigations. A page or frame wait is generally the right scope when a navigation can replace the document. A wait scoped to an element handle cannot survive that handle’s detachment or a navigation that replaces it.

A fixed sleep such as await new Promise(resolve => setTimeout(resolve, 3000)) only waits for elapsed time; it does not establish that the intended element, state, or popup is ready. Prefer a condition-based wait when the outcome is observable. This is practical guidance based on the behavior of the documented wait APIs, not a performance benchmark.

Use a finite timeout that fits the operation and your overall job deadline. Increasing every timeout can make genuine failures take longer to surface. Disabling timeouts can hang a job unless you have a separate cancellation or deadline mechanism.

7. Troubleshooting

Symptom	Likely cause	Fix
waitForSelector times out	The selector is wrong, the element never appears, or it remains hidden.	Confirm the selector against the current DOM, check whether the element is inside a frame, and choose presence versus visible waiting deliberately.
The wait resolves but the click fails	The element exists but an overlay, disabled state, navigation, or application condition prevents the action.	Wait for the actual page state or use a locator for the interaction and handle the application-specific condition separately.
The popup wait times out	The action did not open a target, or the predicate does not match its URL or target.	Register the wait before the action, inspect the URL and target type, and make the predicate specific to the expected popup.
The wrong target is returned	The predicate matches an unrelated target.	Match a more distinctive URL or other target property; avoid predicates that always return true.
target.page() returns null	The matched target is not a page.	Check the target type and only continue with page operations when a page is available.
A wait fails after navigation	The wait was attached to an element handle that was detached or replaced.	Wait from the page or frame that owns the new document, or re-query the element after navigation.
A custom predicate never becomes true	The condition is evaluated in the page context but relies on unavailable Node.js state, or it checks the wrong state.	Pass needed values as arguments and verify the predicate against the live page.
Examples reject an option or method	The installed Puppeteer release differs from the documentation version used by the example.	Check the package version and its matching API documentation; do not assume a method signature from another release.

8. Performance, reliability, and cost

Condition-based waits connect the delay to the state your automation needs. They can continue as soon as the condition is satisfied rather than always spending a fixed sleep duration, while still allowing a timeout to bound the wait. This is a behavioral advantage, not a claim of measured speed.

For reliability, wait for the narrowest observable condition that represents readiness: the element’s visibility, a meaningful page predicate, or the exact popup target. Use finite timeouts, make popup predicates distinctive, and avoid retaining element handles after they are no longer needed. In managed browser environments, overall cost depends on your browser runtime, job duration, and retry policy; these Puppeteer APIs do not provide a cost estimate.

9. Or skip the browser setup

If your goal is to capture a page as an image or PDF rather than interact with a browser session, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. See the API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month with no card.

10. FAQ

Does “Target” mean an HTML element in Puppeteer?

Not necessarily. Puppeteer’s browser Target object represents a browser target, while a DOM element is part of a page. Use the API for the thing you actually need to wait for.

Can I wait for an element that is already present?

Yes. waitForSelector resolves immediately when the selector already matches, subject to any requested visibility condition.

Should I use a selector wait before every click?

No. A locator can wait for presence and action preconditions as part of an interaction. Use a separate wait when you need to observe a state or obtain a handle.

Which wait should I use when a link opens a new tab?

Use browserContext.waitForTarget() with a predicate identifying the new target, then obtain its page and wait for the page content you need.