For new Puppeteer code, click with a locator: await page.locator('button').click();. A locator waits for the element to be visible, enabled, in the viewport, and stable before clicking. Use page.click(selector) when maintaining older code or when you specifically need its lower-level behavior.
Use a locator for a straightforward click
Puppeteer’s page-interactions guide recommends locators for selecting and interacting with page elements. A basic click looks like this:
await page.locator('button').click();Replace button with a selector that identifies the element you intend to click. The locator waits for its documented action preconditions and can retry if the target is not ready. If those conditions are not met before the applicable timeout, the action throws a TimeoutError. See the page interactions guide and Locator.click() API reference.
Choose a selector for the target
CSS selectors are the default, but Puppeteer also supports its own selector syntax for text, accessibility role and name, XPath, and queries through open shadow roots. Examples:
Recommended Free Tools
#1 Best Overall
await page.locator('button#submit').click();
await page.locator('::-p-aria(Submit)').click();
await page.locator('div ::-p-text(Checkout)').click();Prefer a selector that identifies the intended control rather than a broad selector that might match several elements. The official guide describes the supported selector forms.
When to use page.click()
page.click(selector) remains documented and is useful in existing code or when you need its direct page-level behavior:
Rank #2
await page.click('#submit');Puppeteer finds the matching element, scrolls it into view if needed, then clicks its center using Page.mouse. If multiple elements match, it clicks the first; if none match, it throws. Refer to the Page.click() API reference.
Wait when an element appears asynchronously
A locator click is often enough: its action waits for the target to become ready. For a separate, explicit wait, use page.waitForSelector():
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesawait page.waitForSelector('#submit', { visible: true });
await page.locator('#submit').click();waitForSelector can wait for DOM presence, visibility, or a hidden state. Its documented default timeout is 30 seconds, and you can configure it. Unlike a locator action, the wait only establishes the selector condition; it does not itself retry a later click if that action fails. See the waitForSelector() API reference.
Coordinate a click that triggers navigation
Start waiting for navigation at the same time as the click. Waiting only after the click can miss a navigation that begins immediately:
const [response] = await Promise.all([
page.waitForNavigation(),
page.click('a.next'),
]);This pattern is documented in the Page.click() API reference. The response may be null for navigation types that do not produce a response, so avoid assuming it is always an HTTP response.
Locator and page-level click compared
| Situation | Use | What to know |
|---|---|---|
| New interaction code | page.locator(selector).click() |
Recommended by the guide; waits for documented readiness conditions. |
| Existing code or direct page-level interaction | page.click(selector) |
Scrolls into view and clicks the matching element’s center; clicks the first match. |
| Click starts navigation | Promise.all([page.waitForNavigation(), page.click(selector)]) |
Sets up the navigation wait before the click can trigger it. |
| Need an explicit selector wait | page.waitForSelector(selector) |
Waits for presence, visibility, or hidden state; it does not make a later click retry automatically. |
Troubleshoot a click that fails
- No matching element: A missing match makes
page.click()reject. Check that the browser is on the expected page and state, and that the selector matches the intended element. If the page renders it asynchronously, wait for it or use a locator. - Locator timeout: The element may be absent, hidden, disabled, outside the viewport, or moving such that its bounding box is not stable. Check the page state and selector, then address the specific unmet condition rather than disabling checks indiscriminately. Locator actions inherit the page timeout and can have an individual timeout; details are in the Page.locator() reference and Locator class reference.
- The click happens but the next page is not ready: If the click navigates, start
page.waitForNavigation()concurrently with the click usingPromise.all. - A wait succeeds but clicking still fails:
waitForSelectorconfirms its configured selector condition, not every locator click precondition. Use a locator action or inspect whether the element is enabled, visible, in view, and stable. - Using an ElementHandle workflow: The guide treats
ElementHandleas a lower-level alternative. Dispose of a returned handle when finished to avoid retaining it unnecessarily.
Locator configuration can relax particular readiness checks, including viewport, visibility, enabled state, and stable bounding box. Change a check only when the page interaction genuinely requires it; doing so can allow a click in a state the default behavior is designed to wait out. See the Locator class API reference.
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
- Used Book in Good Condition
Or skip the browser setup
If your goal is a screenshot rather than browser interaction, ScreenshotNeo takes a screenshot or PDF from one API request. Its API does not click page elements for you; use Puppeteer when the interaction itself is required.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Before capture, it can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Version note
The linked official Puppeteer documentation covers versions 25.10.0 to 25.12.0. Check the documentation for the version installed in your project if behavior or API details differ.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallFrequently Asked Questions
Does Puppeteer still support page.click()?
Yes. It remains documented as a page-level method; locators are the recommended approach for new interactions.
Can Puppeteer click text or an accessible name instead of a CSS selector?
Yes. Puppeteer supports text and accessibility selector syntax as well as CSS, XPath, and open-shadow-root queries.
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.
