ClickOptions controls the mouse input Puppeteer sends for a click: where it lands, which button is pressed, how long it is held, and how many times it is clicked. Its options do not wait for a page to become ready. For navigation-triggering clicks, start the navigation wait and click together with Promise.all.
This guide follows the live Puppeteer API references: ClickOptions, MouseClickOptions, and Page.click() show version 25.12.0; MouseOptions shows 25.10.0; Offset shows 25.2.1; and LocatorClickOptions shows 25.9.0. Those references do not identify a publication date, so check the live API reference for the version installed in your project.
What are Puppeteer ClickOptions?
ClickOptions is the options type accepted by Puppeteer click actions. It extends MouseClickOptions, which extends MouseOptions. In practical terms, the combined settings let you choose a click coordinate, add a temporary visual highlight, set the number of clicks, specify the press duration, and choose a mouse button.
The settings change the mouse action itself. They do not add an implicit delay for application readiness, wait for an element to appear, or synchronize a resulting navigation.
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 matchWindows 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 reinstallWhat each ClickOptions setting controls
| Option | What it controls | When to use it |
|---|---|---|
debugHighlight |
An optional experimental flag. When enabled, Puppeteer inserts a visible highlight at the click location for 10 seconds. | Use it to inspect where an action is aimed while debugging. It may not work on every page and does not persist across navigation; it is not a reliability or synchronization feature. |
offset |
An optional {x, y} point measured from the top-left corner of the element’s border box. |
Use it when the intended target is not the element’s center. The coordinates are relative to the top-left corner, not a displacement from the default center. |
count |
How many clicks to send; defaults to 1. |
Set a value greater than one only when repeated click input is intended. The option defines the input count, not how the page’s application will interpret it. |
delay |
The time in milliseconds between mouse press and release. | Use it to control how long the button is held. It is not a pause before clicking or after the click. |
button |
Which mouse button to press; defaults to 'left'. |
Choose another button only when the interaction specifically requires it. |
How do I set the click offset in Puppeteer?
Pass an offset object with x and y coordinates to the click call. Both coordinates use the element’s border-box top-left corner as their origin.
await page.click('button.submit', {
offset: { x: 12, y: 8 },
});The numbers are illustrative, not universal settings. Choose coordinates that fall inside the actual target area at the viewport and layout used by your test. If you omit offset, Page.click() clicks the element’s center.
How do I double-click with Puppeteer?
Set count to 2 when you want Puppeteer to send two clicks:
Rank #2
await page.click('button.item', { count: 2 });That sends repeated mouse input; whether the page treats it as a double-click depends on the application and the element. If the interface responds to a double-click event, verify that behavior in the page you are automating rather than assuming the option guarantees an application-level result.
How do I click a button and wait for navigation in Puppeteer?
Register the navigation wait at the same time as the click. Otherwise, the click may trigger navigation before a separately started wait is listening.
const [response] = await Promise.all([
page.waitForNavigation(),
page.click('a.next'),
]);Choose navigation wait options that fit the application’s behavior. A site that updates the URL or document differently may need a different wait condition; there is no single condition that suits every page.
Rank #3
Using Page.click() and locator clicks
Page.click(selector, options)
Page.click() takes a selector, finds the matching element, scrolls it into view if needed, and clicks its center by default. If several elements match, it clicks the first. If none match, the returned promise rejects. This selector-based flow differs from calling ElementHandle.click() on an element handle you already have.
For a selector click with explicit settings, the options can be passed as the second argument:
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 →await page.click('button.submit', {
button: 'left',
count: 1,
delay: 0,
offset: { x: 12, y: 8 },
});Here the values are examples only: offset must be chosen for the element’s geometry, and the inherited defaults are one click and the left mouse button.
Locator click options
Locator clicks use the related LocatorClickOptions type, defined as ClickOptions & ActionOptions. It adds an optional AbortSignal for aborting the locator action. That signal belongs to the locator action options and should not be treated as a universal field on every ClickOptions call surface.
Common click problems and fixes
- The click rejects because no element matched. Check the selector and ensure the element exists before calling
Page.click(). A missing match rejects rather than silently doing nothing. - The click lands in the wrong place. Remove an unnecessary offset to use the default center, or recalculate
xandyfrom the element’s border-box top-left corner. Do not calculate them from the center. - The script misses navigation. Put
waitForNavigation()andclick()in the samePromise.allso the wait is active before the click can navigate. - The page is not ready after the click.
count,delay, anddebugHighlightdo not wait for page readiness. Add an appropriate wait for the specific outcome your script needs. - The temporary highlight is absent or disappears.
debugHighlightis experimental, may not work on every page, and does not survive navigation. Treat it as a debugging aid, not as proof that an interaction succeeded. - A repeated click does not produce the expected application behavior.
countspecifies repeated click input; it does not promise how a particular application handles it. Confirm the target’s expected interaction.
Or skip the browser setup
If your goal is a screenshot rather than an automated click interaction, ScreenshotNeo is an alternative to try first: its screenshot API takes a URL in one request, without setting up a browser. It is not a replacement for Puppeteer when you need to click controls or automate page behavior.
For example, this cURL request saves a screenshot of the Puppeteer API reference as WebP. See the ScreenshotNeo API documentation for request options.
Best Value
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://pptr.dev/api/puppeteer.clickoptions -o shot.webp- 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 ScreenshotNeo free to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Is debugHighlight a wait or a way to make a click more reliable?
No. It is an experimental visual debugging aid, not a synchronization option or reliability guarantee.
Does the offset start from the element’s center?
No. Its origin is the top-left corner of the element’s border box.
Does ClickOptions have an AbortSignal?
Not universally. The documented optional signal is part of LocatorClickOptions through ActionOptions.
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.
