Use page.locator(selector) to describe the element you want, then call an action such as click(), fill(), hover() or scroll(). Puppeteer’s Locator API waits for an element to appear and be ready for the action, and retries when readiness conditions are not met. The current Puppeteer Page interactions guide recommends locators for selecting and interacting with elements.
Create a locator and choose a selector
A locator is a selection strategy, not a saved element handle. Create one from a page with page.locator(), or from a frame with frame.locator(), then perform an action on it:
await page.locator('button').click();
await page.locator('input[name="email"]').fill('reader@example.com');CSS selectors can be passed directly. Puppeteer also supports its own selector syntax for text, accessibility attributes such as role and name, XPath, and queries that cross shadow roots. The Page locator method can also accept a function. Choose a selector that identifies the intended control rather than relying on incidental layout or styling classes; selectors tied to stable attributes or clear semantics are often easier to maintain.
For example, a broad selector such as button may match several controls. Narrow it to a stable attribute or scope it to a relevant part of the page so the locator describes the intended target.
#1 Best Overall
Use the locator action that matches the task
Click
Call click() to activate a button, link, or other clickable element:
await page.locator('button[type="submit"]').click();For clicking, Puppeteer checks that the element is present, in the viewport, visible, enabled, and has a stable bounding box across two consecutive animation frames. If it is not ready, the locator operation can retry.
Fill form controls
fill(value) selects an appropriate way to enter the value at runtime. Documented targets include input, textarea, select, and contenteditable elements. Checkboxes, radio buttons, and switches take a boolean value:
Rank #2
await page.locator('input[name="email"]').fill('reader@example.com');
await page.locator('select[name="region"]').fill('west');
await page.locator('input[name="updates"]').fill(true);Use the value expected by the control: for example, a select is filled with an option value, while a checkbox is set with a boolean.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Hover and scroll
Use hover() to move the pointer over the located element, such as a menu trigger, and scroll() when the page needs to bring the target into view:
await page.locator('[data-menu="products"]').hover();
await page.locator('#details').scroll();Filter, map, wait, and race locators
The Locator API also documents filter(predicate), map(mapper), wait(), and waitHandle(). A filter can express a condition the located value must meet; if it does not yet match, the locator waits and retries. A map transforms the located value. race(locators) lets competing locators race so only one receives the action. Use these when they clarify a real selection or timing problem rather than adding complexity to a simple selector.
Let locators handle readiness before tuning waits
Locator actions wait for presence and action readiness, and retry when readiness checks fail. This is useful on pages where elements appear after client-side rendering, become enabled later, or move while an animation is running. Prefer that built-in behavior over adding fixed delays as a first response.
The Locator API includes cloning and configuration methods for timeout, visibility, viewport handling, waiting for enabled state, and waiting for a stable bounding box. Adjust these deliberately when the page’s behavior requires it. Disabling a check can hide the symptom without fixing why the target is absent, obscured, disabled, or moving.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Handle navigation triggered by a click
When an interaction causes navigation, start the navigation wait and click together. Starting the wait separately can race with a fast navigation:
const [response] = await Promise.all([
page.waitForNavigation(),
page.locator('a.next').click(),
]);response is the navigation response, if one is returned. Coordinating both promises ensures the wait is in place before the click can trigger navigation.
Use waitForSelector or ElementHandle only when needed
Use page.waitForSelector() or an ElementHandle when the locator API does not provide the functionality you need. waitForSelector() waits for DOM availability, but it does not automatically retry a later action if that action fails. It returns a handle; dispose of the handle when finished to avoid retaining resources.
Some page-level methods, including page.click(selector), page.type(selector), and page.hover(selector), use waitForSelector() for backward compatibility. A locator keeps the selection strategy paired with the action and is the recommended interaction approach in the current guide; a handle represents a concrete element reference and requires more explicit lifecycle management.
PC 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 & 11Crashes, 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 minuteBest Value
- Used Book in Good Condition
Troubleshoot locator failures
- The locator never finds an element: Check that the selector matches the page’s actual DOM, that the relevant frame is being queried, and that the content has loaded. Narrowing or correcting the selector is preferable to adding an arbitrary delay.
- The element is found but click keeps retrying: Check whether it is visible, enabled, inside the viewport, or still moving. A covering overlay or animation can prevent the readiness checks from passing.
- A fill action targets the wrong control: Make the selector more specific and confirm that the field’s name, value, or semantic type matches the intended control. For checkboxes, radio buttons, and switches, pass a boolean.
- A navigation wait hangs or misses the navigation: Put
page.waitForNavigation()and the locator click in the samePromise.all()call. - A handle-based workflow retains resources: Dispose of handles returned from lower-level selection methods when you are done with them.
Or skip the browser setup
If the goal is to capture a page as an image or PDF rather than interact with its elements, ScreenshotNeo offers a one-request screenshot API. It is made by Yorker Media; see ScreenshotNeo or its API documentation.
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 or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; these steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots.
Sign up free for 1,000 screenshots a month—no card required.
Frequently Asked Questions
Can I create a Puppeteer locator from a frame?
Yes. Use frame.locator(selector) to create a locator scoped to that frame.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Can a Puppeteer locator use something other than CSS?
Yes. Puppeteer supports selector syntax for text, accessibility attributes such as role and name, XPath, and queries across shadow roots; the Page locator method can also take a function.
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.
