Main Website
Updated on
February 9, 2024

Click in Puppeteer: Guide to Master Puppeteer’s Clicking Methods

One of the fundamental actions you’ll frequently perform in Puppeteer is clicking elements on a web page. In this article, we will delve into the three most common methods available in Puppeteer for clicking elements and explore their functionality.

Our focus will revolve around three key methods:

Also, we will touch upon advanced Click configurations:

Each of these methods offers a unique approach to identify and interact with elements on a webpage. By the end of this article, you’ll have a comprehensive understanding of when and how to employ these methods effectively for your scraping, testing automation and other web automation needs.

A common concern when automating interactions is ensuring that the target element is visible. Puppeteer addresses this issue by automatically scrolling the page to bring the element into view before performing the click. This ensures the reliability of your interactions, even if the element initially lies outside the visible area.

Methods for Clicking Different Web Page Elements

Puppeteer provides a versatile set of methods for clicking various types of web page elements. Here’s a brief overview of the methods and their typical use cases:

1) Selector Method: It is the most common method and is used to click elements selected by CSS selectors. For example, you can click on a “Submit” button by specifying its CSS selector.

CSS selectors are generally the easiest and fastest way to interact with elements when using Puppeteer. They are ideal for standard HTML elements with unique IDs, classes, or attributes, and are well-suited for navigating element relationships like parent-child or sibling connections. However, they may lack the flexibility needed for more complex queries.

2) XPath Method: When you need to interact with elements using XPath expressions, Puppeteer offers the XPath method. It is particularly useful for complex element selection.

XPath provides a more flexible but slightly more complex way to interact with elements. It's particularly useful when you need to navigate the XML structure of the page or make queries based on textual content. XPath can handle more intricate selection criteria based on page structure, but it may be slower and harder to read than CSS selectors.

3) Text Method: If you want to click an element based on its text content, the Text method is your go-to option. For instance, you can use it to click a link with specific anchor text.

Text-based methods are the most intuitive, allowing you to interact with elements based on their visible text content. This approach is straightforward and doesn't require a deep understanding of the underlying HTML structure. However, it may not be reliable if the same text appears in multiple places or if the text is dynamically generated.

Click using Selector

The Selector method in Puppeteer is a versatile and widely used approach for clicking on web page elements. This method allows you to select elements using CSS selectors and perform a click action on them. Let’s dive into the details of how to use the Selector method effectively.

Using the Selector Method

The Selector method is part of Puppeteer’s API and is accessed via the, options) function. Here’s how it works:

  • selector: This parameter is a CSS selector string that specifies the element you want to click. It can be used to target elements based on their HTML attributes, classes or IDs.
  • options: It is an optional parameter. You can provide an options object to fine-tune the click action. For example, you can set a delay before the click or specify which mouse button to use.

Example: Clicking a “Submit” Button

Let’s illustrate the Selector method with an example. Suppose you have a web page with a “Submit” button that you want to click using Puppeteer. Here’s how you can do it:

In this example:

  • We launch a headless browser and create a new page.
  • We navigate to a sample webpage, such as “”.
  • Using the method, we select the Submit button by specifying its CSS selector, which is #submit-button. This selector targets an element with the ID attribute “submit-button.”
  • Finally, we close the browser.

Click using XPath

Puppeteer’s XPath method provides an alternative approach for clicking on web page elements. XPath is a powerful language to navigate XML documents, and in the context of web automation, it allows you to pinpoint elements based on their position in the document structure or their attributes. Let’s delve into how to use the XPath method effectively.

Using the XPath Method

To use the XPath method in Puppeteer, you can leverage the function with an XPath expression as the selector. 

XPath expression: Instead of using CSS selectors as in the Selector method, you provide an XPath expression that specifies the element you want to click. This expression can be tailored to match elements based on their attributes, tag names, or relative position within the HTML structure.

Example: Clicking an Element using XPath

Let’s illustrate the XPath method with an example. Imagine you have a web page that contains a search input field, and you want to click it to initiate a search. Here’s how you can achieve this using Puppeteer’s XPath method:

In the provided example, we launch a headless browser and initialize a new page using Puppeteer. After this setup, we proceed to navigate to a sample webpage. Now to interact with a specific element on the page, we employ the method. In this instance, we utilize an XPath expression, xpath=//input[@id="search-input"], as our selector. This expression precisely targets an <input> element distinguished by its unique ID attribute, namely search-input. By executing the method with this XPath expression, we trigger a click action on the designated element. Lastly, we hit enter to initiate the search and wait 2 seconds to close the browser, completing the automation process.

Click using Text

Puppeteer’s Text method provides an intuitive way to interact with web page elements based on their textual content. This method is particularly useful when you want to click buttons, links, or other elements using their visible text.

Keep in mind that if there are two elements that match the text condition, Puppeteer will select the first element in page hierarchy, thus this method is quite limited unless you are aiming to click specific unique text.

Let’s explore how to use the Text method effectively with two practical examples.

Example 1: Clicking a Button via Button Text

Suppose you have a web page with a “Submit” button, and you want to click it using Puppeteer based on its visible text. Here’s how you can achieve this:

In this example, we start by launching the headless browser and initializing a new page using Puppeteer. After navigating to a sample webpage, we utilize the method with the selector text=Submit. This selector effectively targets the Submit button on the page based on its visible text, enabling us to initiate the click action precisely. Subsequently, we conclude the automation process by closing the browser.

Example 2: Clicking Links by Link’s Anchor Text

Consider a webpage with various links, each having descriptive anchor text. You want to click a specific link by matching its anchor text. Here’s how to do it:

In this example, after navigating to a sample webpage, we use the method with the selector text=Read More. This selector identifies the link with the anchor text, allowing us to initiate a click action on the specific link. 

Advanced Clicking Configurations

While Puppeteer’s basic clicking methods are powerful on their own, you can enhance your automation scripts by implementing advanced clicking configurations. 

Click After Time Delay

Sometimes it is necessary to introduce a time delay before performing a click action. This can be useful to ensure that a web page fully loads or to simulate a more realistic user interaction for the purpose of web scraping. Here’s an example of how to click an element after a specific time delay:

The above code launches a headless browser, navigates to a webpage, and then pauses for a specified period (in this case, 2 seconds) using page.waitForTimeout(2000). This delay allows the webpage to fully load or perform any necessary operations before proceeding to click the “Submit” button.

We can also introduce a randomized time delay to simulate more natural user interactions, which would provide an even greater benefit for web scraping. For instance, the code below demonstrates how to add a randomized time delay before clicking on an element.

In this example, after navigating to a webpage, we define a getRandomDelay() function that generates a random time delay between a specified range (in this case, between 3 and 6 seconds). We then calculate a random delay using getRandomDelay(3000, 6000) and use  page.waitForTimeout(randomDelay) to pause the script for the generated time. After the randomized delay, we click on an element with the ID #example-element using

Multiple Clicks

If you need to perform multiple clicks with intervals between them, you can achieve this by combining Puppeteer’s clicking and time delay functions. This can be useful when handling popups. For instance a promotional pops up - in this case you want to close it first and then continue with your other click. Here’s an example that demonstrates how to perform multiple sequential clicks on web page elements:

In this code, after navigating to a webpage, we perform multiple sequential clicks using on three different elements with their respective IDs.

To add a time delay between multiple clicks, you can use page.waitForTimeout() between each click. Below is the code that shows how to do this.

In this code, we introduce time delays between the clicks. For instance, we wait for 1 second after the first click and then wait for 2 seconds after the second click. By adding time delays between multiple clicks, we can ensure that each action occurs at the desired timing intervals, making Puppeteer interaction more human-like.

Click, Fill in Form and then Click Again

When handling submit forms, especially in the case of automated application testing, you may need to click an element, fill in a form that appears, and then click another element. Here’s an example of how to achieve the sequence of actions:

The above code clicks on an element that triggers the display of a form. Further, it uses the page.type() method to input data into the form fields. After filling in the required information, it initiates a click on the “Submit” button located within the form. This sequence of actions effectively demonstrates how Puppeteer can automate multi-step interactions involving forms.

How to Solve Common Click Errors in Puppeteer?

In this section, we’ll address the common click errors in Puppeteer and how to solve them.

Puppeteer Button Click not Working

When you encounter issues with Puppeteer not clicking buttons as expected, it can be due to various reasons. Here are some steps to resolve this issue:

  • Wait for Element: Ensure that the button element is visible and interactable before attempting to click it. You can use page.waitForSelector() to wait for the button to appear on the page.
  • Frame Switching: If the button is inside an iframe, make sure to switch to that frame using page.frames() before attempting to click it.
  • CSS Selector: Double-check the CSS selector you are using to select the button. A wrong or outdated selector may result in Puppeteer not finding the element.
  • Timeouts: Adjust the timeout settings in case the button takes longer to load. Use page.setDefaultTimeout() to set a longer timeout if needed.
  • Error Handling: Implement error handling to catch and handle any exceptions that might occur during the click operation.

Puppeteer Node is either not clickable or not an HTMLElement

This error typically occurs when Puppeteer attempts to click on an element that is not an HTML element or is not interactable. To resolve this issue, do the following:

  • Check Element Type: Verify that the element you are trying to click is indeed an HTML element. If it’s a non-standard element or not an actual part of the DOM, Puppeteer might have trouble interacting with it.
  • Visibility: Ensure that the element is visible on the page. You can use page.waitForSelector() with the visible: true option to wait for the element to become visible.
  • Interactivity: Confirm that the element is interactable. Some elements may require user interactions i-e., scrolling, hovering before they can be clicked.

Captcha Boxes

Captcha boxes are specifically designed to prevent automated interactions, making them challenging for Puppeteer. Solving captchas programmatically may not always be feasible, as captchas are designed to be human-readable and hard for bots to figure out. 

One approach is to use third-party captcha solving services like 2Captcha that integrate with Puppeteer. However, this may incur additional costs. Alternatively, you can consider automating interactions with websites that do not implement captchas or using Puppeteer for non-captcha related tasks.

Also, modifying the user agent of the headless browser can also help in making the Captcha appear significantly less often. Click here to learn more about setting up user agent in Puppeteer. Alternatively, you can also test using Puppeteer extra’s Stealth plugin which adds additional functionality to make the automated browser appear more human-like.

Finally, you can test using proxies in Puppeteer which can help decrease the amount of Captchas that you receive in Puppeteer.


In this article, we discussed Puppeteer’s clicking methods, including Selector, XPath and Text-based clicks. Additionally, we covered advanced clicking configurations, such as introducing time delays and performing multiple clicks along with some common click errors. While Puppeteer is a powerful tool for web automation, certain challenges like captcha boxes may require additional configuration.

Related Articles

Using Puppeteer on AWS Lambda for Scraping

Scroll in Puppeteer: Scroll to Bottom, Top, or Into View

5 Puppeteer Alternatives For Scraping & Application Testing