Use page.locator(selector) to describe which element you want, then call an action such as click(), fill(), hover() or scroll(). Puppeteer’s Locator API waits for the target to be present and ready, and retries an action when readiness conditions are not met. The current Page interactions guide recommends locators for selecting and interacting with elements. Puppeteer Page interactions guide
Create a locator and choose a selector
A locator stores a way to find a value and perform an action on it. Create one from a page or frame:
As an Amazon Associate I earn from qualifying purchases.
const button = page.locator('button');
await button.click();
const frameInput = frame.locator('input');
await frameInput.fill('value');Pass a CSS selector directly when it identifies the intended target. Puppeteer also supports selector forms for text, accessibility role and name, XPath, and queries that cross shadow roots. The Page locator method can also take a function. Use a selector that describes the target clearly and is unlikely to break when incidental page markup changes.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →For a page with several buttons, a broad selector such as button may be ambiguous. Narrow it to the relevant control, for example with a more specific CSS selector or an appropriate role-and-name selector. Check Puppeteer’s selector documentation for syntax supported by the version installed in your project.
#1 Best Overall
Click, fill, hover, and scroll
Click a control
await page.locator('button[type="submit"]').click();For a click, Puppeteer checks that the element is in the viewport, visible, enabled, and has a stable bounding box across two consecutive animation frames. If readiness conditions are not met, the Locator API retries the operation. Locator API reference
Fill a form field
await page.locator('input[name="email"]').fill('[email protected]');
await page.locator('textarea[name="message"]').fill('Hello');
await page.locator('select[name="region"]').fill('US');fill() chooses an appropriate filling method at runtime. Documented target types include contenteditable, select, textarea, and input. For checkboxes, radio buttons, and switches, pass a boolean value. Locator API reference
Rank #2
Hover or scroll to an element
await page.locator('[data-menu="products"]').hover();
await page.locator('#results').scroll();These actions use the locator’s selection strategy rather than requiring you to first retrieve and manage an element handle. The Locator API also documents wait(), waitHandle(), filter(predicate), and map(mapper). A filter waits and retries when its predicate does not yet match; a mapper transforms the located value. Locator API reference
Use locators for changing or competing targets
When a page renders asynchronously or its layout changes, a locator can retry while the target becomes ready, rather than leaving you to manually coordinate a selector wait and a later action. The locator API also includes race(locators) for competing locators; its documentation says only one locator receives the action.
Locators can be cloned and configured with options related to timeout, visibility, viewport handling, waiting for enabled state, and waiting for a stable bounding box. These settings are useful when the default behavior does not fit the page. Change them deliberately: disabling a readiness check can hide the cause of a flaky interaction instead of fixing it. See the Locator API reference for the available configuration methods for your installed version.
Wait for navigation without a race
If a click triggers navigation, start the navigation wait and the click together. Starting the wait separately can race with the click, so the navigation may begin before Puppeteer is waiting for it.
const [response] = await Promise.all([
page.waitForNavigation(),
page.locator('a.next').click(),
]);This pattern coordinates the two promises; response contains the navigation response when one is returned. See Puppeteer’s Page API documentation for waitForNavigation().
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
When to use waitForSelector or an ElementHandle
Use the Locator API by default for selecting and interacting with elements. Reach for page.waitForSelector() or an ElementHandle when you need functionality the locator API does not provide.
Best Value
- Used Book in Good Condition
| Approach | What it gives you | What to account for |
|---|---|---|
| Locator | A selection strategy coupled to an action, with readiness waiting and retries. | Choose a precise selector and confirm the API against the installed Puppeteer version. |
waitForSelector() and handle |
A lower-level wait for DOM availability followed by direct access to an element. | The wait does not automatically retry a later action if that action fails. Dispose returned handles when finished to prevent memory leaks. |
Some page-level methods, including page.click(selector), page.type(selector), and page.hover(selector), use waitForSelector() for backward compatibility. The Page interactions guide describes that route as lower-level than locators. Puppeteer Page interactions guide
Troubleshoot locator actions
- The selector finds the wrong element or is ambiguous: narrow it to a more specific CSS selector, or use a selector based on text or accessibility role and name when that better expresses the target.
- The click keeps waiting or retrying: check that the target exists, is visible, enabled, in the viewport, and can settle into a stable bounding box. If the page has an overlay or a disabled control, address that page state rather than immediately turning off checks.
fill()does not suit the target: confirm the element is one of the documented target types. Use a boolean value for a checkbox, radio button, or switch.- A navigation wait misses the navigation: start
page.waitForNavigation()and the locator click together withPromise.all(). - A handle-based action fails after a selector wait: remember that
waitForSelector()only waits for DOM availability; it does not add locator-style retries to a subsequent action. Prefer a locator when the task is a selection followed by interaction. - Behavior differs from an example: check the Puppeteer version installed in the project. The current guide search result identifies version 25.12.0, but the API documented for that version may differ from older installed releases. Page interactions guide · Locator API reference
Or skip the browser setup
If your task is to capture a page rather than automate its controls, ScreenshotNeo can return a screenshot or PDF from one GET request. It accepts cookie or 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 and other MCP clients. The free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots. See the ScreenshotNeo site and API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Does a locator select an element immediately when it is created?
No. It stores the selection strategy; an action such as click() or fill() performs the lookup and interaction.
Can I create a locator inside a frame?
Yes. Use frame.locator(selector) to create a locator scoped to that frame.
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.
