Use await page.$('selector') to get the first matching element if it is already in the DOM; it returns null if there is no match. If the element may appear later, use await page.waitForSelector('selector'). For most ordinary interactions, Puppeteer recommends Locators; when an operation specifically needs a handle, call await page.locator('selector').waitHandle().
Get a handle to an element that already exists
page.$() queries the page for the first matching element. It resolves to an ElementHandle when it finds one, or null when it does not. Always check the result before calling handle methods.
As an Amazon Associate I earn from qualifying purchases.
const button = await page.$('button.submit');
if (button) {
try {
await button.click();
} finally {
await button.dispose();
}
}The selector can be CSS or Puppeteer’s supported selector syntax. See the Page.$() API reference.
Wait for an element and get its handle
Use page.waitForSelector() if the element is added after the page loads or otherwise is not immediately available. It waits for a matching element and returns its handle. The documented default timeout is 30,000 milliseconds; pass a different timeout in milliseconds, or 0 to disable the timeout.
#1 Best Overall
const button = await page.waitForSelector('button.submit', {
visible: true,
timeout: 10_000,
});
if (button) {
try {
await button.click();
} finally {
await button.dispose();
}
}Visibility is not required by default. Set visible: true when the element must be visible. The hidden option waits for an element to be hidden or absent; in that case the method can resolve to null. If a selector does not appear before the timeout, the call throws. You can also pass an abort signal to cancel the wait. Consult the Page.waitForSelector() reference for the current options and return behavior.
Use a Locator when interaction is the goal
Puppeteer’s page-interactions guide calls Locators the recommended way to select and interact with elements. A Locator describes how to find the target and waits for presence and action preconditions, retrying an action when the element is not ready. For a click, prefer a Locator directly unless you need an ElementHandle for a handle-specific operation.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
await page.locator('button.submit').click();If you do need the handle, bridge from the Locator with waitHandle():
const button = await page.locator('button.submit').waitHandle();
try {
// Use handle-specific methods here.
await button.click();
} finally {
await button.dispose();
}waitHandle() waits for the Locator to obtain a handle. See the Puppeteer page interactions guide and Locator.waitHandle() API reference.
Rank #3
Choose a selector and query the right scope
Use the selector form that fits the target
CSS selectors are supported, and Puppeteer also provides syntax for text, accessibility role or name, XPath, and shadow-root queries. For example, the documented XPath form for a page query is ::-p-xpath(//h2); Locator selectors can include forms such as ::-p-aria(Submit). Choose a selector that identifies the intended element in your page rather than assuming CSS is the only option.
Find a child relative to a parent handle
If you already have a handle to a container and need a descendant within it, call $(selector) on that handle. The search is scoped to the current element and returns a matching handle or null.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
const card = await page.$('.product-card');
if (card) {
try {
const title = await card.$('h2');
if (title) {
try {
console.log(await title.evaluate(element => element.textContent));
} finally {
await title.dispose();
}
}
} finally {
await card.dispose();
}
}See ElementHandle.$() in the API reference.
Dispose handles and account for page lifecycle
An ElementHandle refers to an in-page DOM element and prevents that element from being garbage-collected while the handle is live. Dispose handles when you are finished with them, especially in longer-running flows. A try/finally block ensures cleanup even if an operation throws.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Puppeteer also automatically disposes handles when their frame navigates or their parent execution context is destroyed. A handle is therefore not a durable reference across navigation. A handle returned by ElementHandle.waitForSelector() is scoped to that element and does not work across navigations or if the element is detached; this differs from Page.waitForSelector(), which the documentation says works across navigations. See the Puppeteer API reference and ElementHandle.waitForSelector() reference.
Troubleshoot common handle problems
page.$()returnednull: no element matched when the query ran. Check the selector and page state, or usewaitForSelector()if the element is added later.waitForSelector()timed out: the selector did not match before the timeout. Check that the expected page or frame is loaded, confirm the selector against the DOM, and adjust the timeout if the page legitimately needs longer.- The returned handle is
nullwhile waiting for hidden state: this can be the expected result when usinghidden: trueand the selector is absent. - The element exists but the action cannot proceed:
waitForSelector()does not require visibility unless you setvisible: true. For ordinary actions, consider a Locator, which waits for action preconditions. - A handle becomes unusable after navigation or removal: handles are tied to their frame and execution context. Query again after navigation; for a descendant wait, remember that detaching the parent invalidates its scoped wait.
- Cleanup is skipped after an error: put handle use in
try/finallyand dispose it in thefinallyblock.
Or skip the browser setup
If your goal is a screenshot rather than DOM interaction, ScreenshotNeo provides a website screenshot API. One GET request returns an image or PDF; consult the API documentation for parameters.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and each response identifies the page verdict and billing status in headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month, with no card required.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Frequently Asked Questions
Can I construct an ElementHandle directly?
No. Use Puppeteer’s page, Locator, or element query APIs to obtain one; the API reference marks the ElementHandle constructor as internal.
Does waitForSelector wait until an element is visible by default?
No. Visibility defaults to false; pass { visible: true } when visibility is required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
