Puppeteer Mouse Click Options Explained

page.mouse.click(x, y, options) clicks at viewport coordinates. Its options are button, count, and delay. Use button: 'right' for a right click and count: 2 for a double click. For ordinary element interaction, Puppeteer’s current guide recommends locators because they wait for an element to be ready; the selector-based page.click() remains useful when you need its specific behavior or options such as offset.

1. Runnable setup

The examples use Puppeteer’s JavaScript API. Install Puppeteer in a project with Node.js:

npm install puppeteer

Save this as click-options.js and run it with node click-options.js. It opens a page, makes a coordinate click, and closes the browser cleanly.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.setViewport({ width: 1280, height: 800 });
    await page.setContent('<button id="target">Click me</button>');

    // The button is centered in the viewport in this minimal example.
    await page.mouse.click(640, 400);
    console.log('Clicked at viewport coordinates (640, 400)');
  } finally {
    await browser.close();
  }
})();

2. Mouse click options and defaults

MouseClickOptions extends MouseOptions. The button option is inherited. The following reflects the Puppeteer API reference; consult the live reference for changes between releases.

Option	Default	Meaning	Use it for
button	'left'	Mouse button to press. Valid values are 'left', 'right', 'middle', 'back', and 'forward'.	Testing alternate-button behavior supported by the page or browser.
count	1	Number of clicks to perform.	Double-click or other multi-click interactions.
delay	No explicit default shown in the reference	Time in milliseconds between mouse press and release.	Interactions that depend on how long the button is held.

Pass the options object as the third argument after x and y. For example:

await page.mouse.click(400, 250, {
  button: 'left',
  count: 1,
  delay: 80,
});

Right click

Set button to 'right'. This dispatches a right-button click at the specified viewport point; browser context-menu behavior can depend on the environment and page handlers.

await page.mouse.click(400, 250, { button: 'right' });

Double click

Set count to 2. The click count lets the page receive a multi-click sequence, which is useful when testing interfaces that react to double clicks.

await page.mouse.click(400, 250, { count: 2 });

Middle, back, and forward buttons

These are supported button values. Whether a particular action has an effect depends on browser behavior, operating environment, and page event handling.

await page.mouse.click(400, 250, { button: 'middle' });
await page.mouse.click(400, 250, { button: 'back' });
await page.mouse.click(400, 250, { button: 'forward' });

Press duration

delay sets the interval, in milliseconds, between mouse press and release. Use a nonzero value only when the interaction needs a held press. It is not a general-purpose wait for the page to finish responding.

await page.mouse.click(400, 250, { delay: 150 });

3. Coordinates, selectors, and locators

API	Targeting	Readiness behavior	Notable options
page.mouse.click(x, y, options)	Viewport coordinates in main-frame CSS pixels, measured from the viewport’s top-left.	Low-level pointer action; you choose the point and handle readiness.	button, count, delay.
page.click(selector, options)	Selector; scrolls the matched element into view and clicks its center by default.	Errors if no element matches; if several match, clicks the first.	Click options plus offset and experimental debugHighlight.
Locator click	Locator for the element.	Automatically checks viewport presence, visibility, enabled state, and a stable bounding box across two animation frames.	Use the locator API for ordinary element interaction and its built-in readiness checks.

Choose page.mouse.click when you need to position the pointer at a precise coordinate or are testing a low-level pointer interaction. Choose a locator when the goal is to interact with an element and you want Puppeteer’s readiness checks. Use page.click when its selector-based center click or its ClickOptions fit the task.

Coordinate clicks

The coordinates are CSS pixels relative to the main-frame viewport, not the full page. Scrolling changes which content occupies a viewport coordinate. If the target is outside the viewport, a coordinate click will not automatically scroll it into view.

// Click at x=320, y=180 from the viewport's top-left.
await page.mouse.click(320, 180);

Selector clicks and their extra options

page.click(selector, options) locates the element, scrolls it into view if necessary, and clicks its center by default. If multiple elements match, the first match is used, so prefer a selector that identifies one intended element.

offset targets a point relative to the top-left of the element’s border box. debugHighlight is experimental: it inserts a page element highlighting the click location for 10 seconds, may not work on every page, and does not persist across navigation. These options belong to selector-based page.click; they are not options for page.mouse.click(x, y, options).

// Click a point offset from the element's top-left border-box corner.
await page.click('#save', { offset: { x: 12, y: 8 } });

// Experimental visual aid; support can vary by page.
await page.click('#save', { debugHighlight: true });

Locator clicks for normal interactions

The current Puppeteer guide recommends locators for ordinary element interaction. A locator click waits for the element to be in the viewport, visible, enabled, and stable across two animation frames before clicking. If those checks do not cover a specialized interaction, lower-level APIs remain available.

await page.locator('#save').click();

4. Wait for navigation without a race

A click that starts navigation can race with a separately registered navigation wait. Start both operations together with Promise.all:

const [response] = await Promise.all([
  page.waitForNavigation(),
  page.click('a.next-page'),
]);
console.log('Navigation completed:', response?.url());

Use the same pattern with a locator if that is how you perform the click:

const [response] = await Promise.all([
  page.waitForNavigation(),
  page.locator('a.next-page').click(),
]);

For a single-page application that changes content without a full navigation, wait for the resulting URL, selector, or application state instead of assuming a navigation will occur.

5. Complete example: choosing an API and handling navigation

This example uses a locator for a regular link click and registers the navigation wait before the click. Replace the URL and selector with the page under automation.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com');

    const [response] = await Promise.all([
      page.waitForNavigation(),
      page.locator('a').click(),
    ]);

    console.log('Current URL:', page.url());
    console.log('Response status:', response?.status());
  } finally {
    await browser.close();
  }
})();

To perform a coordinate click instead, identify the target’s current viewport coordinates and call page.mouse.click(x, y, options); keep the navigation wait concurrent with that call as well.

6. Common problems and fixes

Symptom	Likely cause	Fix
The click lands on the wrong item.	Coordinates are viewport-relative and may be stale after scrolling, resizing, or layout changes.	Recompute the target point after layout settles, or use a locator for element-based interaction.
A coordinate click does nothing.	The point is outside the viewport, the target moved, or an overlay intercepts the click.	Check the current viewport and page state; use a locator or selector click when appropriate, and inspect overlays.
page.click clicks an unexpected duplicate.	Multiple elements match and the first match is clicked.	Narrow the selector so it identifies the intended element uniquely.
page.click reports no matching element.	The selector is wrong, or the element has not appeared yet.	Correct the selector and wait for the expected element or use a locator that can wait for readiness.
The click happens but navigation times out or is missed.	The navigation wait was registered after the click, or the action only changes SPA state.	Use Promise.all to start a real navigation wait and click together; for SPA changes, wait for the relevant URL or page state.
A double-click handler does not run.	The page may require a different target, or the element is not ready or is covered.	Confirm the target and interaction state, then try { count: 2 } or a locator click as appropriate.
A right click does not show the expected menu.	The page may suppress the context menu, or the test environment handles it differently.	Check page event handlers and assert the intended right-click behavior directly.
Text selection or dragging does not behave like a physical mouse.	page.mouse dispatches synthetic mouse events and does not fully reproduce physical mouse behavior; the Mouse reference says dragging and selecting text are not possible using page.mouse.	Use DOM selection APIs for text selection. For dragging, use an interaction method suited to the application and validate its event behavior.

7. Reliability, performance, and cost

Coordinate clicks are direct and simple, but depend on the current viewport and layout. Selector and locator interactions express intent in terms of an element; locator readiness checks can avoid clicks against elements that are hidden, disabled, or moving. Avoid adding arbitrary delays as a substitute for waiting on the specific navigation or page state your workflow needs.

Choose the lightest interaction that still represents the behavior under test. For repeated automation, stable selectors and explicit state waits are easier to maintain than hard-coded coordinates. Puppeteer’s cited API references do not provide a performance benchmark or a monetary cost figure for these click methods; runtime and infrastructure costs depend on the application and browser workload.

8. Or skip the browser setup

If your goal is a clean screenshot rather than testing a pointer interaction, ScreenshotNeo returns an image or PDF from one GET request. Its API documentation covers the request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted and removed before the shot, along with supported newsletter popups and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers say the page verdict and whether it was billed. An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.

9. FAQ

Does delay wait for the page after clicking?

No. It is the time in milliseconds between mouse press and release. Wait for navigation or the resulting page state separately.

Can I use offset with page.mouse.click?

No. offset is documented on selector-based page.click options and is measured from the element’s border-box top-left.

Should I use page.click or a locator?

For ordinary element interaction, the current guide recommends locators for their automatic readiness checks. page.click remains documented and can be useful when its selector-based behavior or options fit your task.

Can Puppeteer’s mouse fully imitate a physical mouse?

No. Mouse events are synthetic and do not fully reproduce physical-user behavior. In particular, the Mouse reference says dragging and selecting text are not possible using page.mouse.

10. Official references

• MouseClickOptions and MouseOptions
• Mouse.click and Mouse class
• Page.click and ClickOptions
• Puppeteer page interactions guide
• Page.waitForNavigation