<titledata-rh="true">Page interactions | Puppeteer</title><metadata-rh="true"name="viewport"content="width=device-width,initial-scale=1"><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://pptr.dev/next/guides/page-interactions"><metadata-rh="true"property="og:locale"content="en"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docsearch:counter"content="3"><metadata-rh="true"property="og:title"content="Page interactions | Puppeteer"><metadata-rh="true"name="description"content="Puppeteer allows you interact with the pages in various ways."><metadata-rh="true"property="og:description"content="Puppeteer allows you interact with the pages in various ways."><linkdata-rh="true"rel="icon"href="/img/favicon.ico"><linkdata-rh="true"rel="canonical"href="https://pptr.dev/next/guides/page-interactions"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/next/guides/page-interactions"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/next/guides/page-interactions"hreflang="x-default"><linkdata-rh="true"rel="preconnect"href="https://DVKY664LG7-dsn.algolia.net"crossorigin="anonymous"><linkrel="search"type="application/opensearchdescription+xml"title="Puppeteer"href="/opensearch.xml">
<p>Puppeteer allows you interact with the pages in various ways.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="locators">Locators<ahref="#locators"class="hash-link"aria-label="Direct link to Locators"title="Direct link to Locators"></a></h2>
<p>Locators is a new, experimental API that combines the functionalities of
waiting and actions. With additional precondition checks, it
enables automatic retries for failed actions, resulting in more reliable and
less flaky automation scripts.</p>
<divclass="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><divclass="admonitionHeading_Gvgb"><spanclass="admonitionIcon_Rf37"><svgviewBox="0 0 14 16"><pathfill-rule="evenodd"d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><divclass="admonitionContent_BuS1"><p>Locators API is experimental and we will not follow semver for breaking changes
in the Locators API.</p></div></div>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="use-cases">Use cases<ahref="#use-cases"class="hash-link"aria-label="Direct link to Use cases"title="Direct link to Use cases"></a></h3>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="waiting-for-an-element">Waiting for an element<ahref="#waiting-for-an-element"class="hash-link"aria-label="Direct link to Waiting for an element"title="Direct link to Waiting for an element"></a></h4>
<p>The following preconditions are automatically checked:</p>
<ul>
<li>Waits for the element to become
<ahref="https://pptr.dev/api/puppeteer.elementhandle.isvisible/"target="_blank"rel="noopener noreferrer">visible</a> or hidden.</li>
</ul>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="waiting-for-a-function">Waiting for a function<ahref="#waiting-for-a-function"class="hash-link"aria-label="Direct link to Waiting for a function"title="Direct link to Waiting for a function"></a></h4>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="clicking-an-element">Clicking an element<ahref="#clicking-an-element"class="hash-link"aria-label="Direct link to Clicking an element"title="Direct link to Clicking an element"></a></h4>
<p>The following preconditions are automatically checked:</p>
<ul>
<li>Ensures the element is in the viewport.</li>
<li>Waits for the element to become
<ahref="https://pptr.dev/api/puppeteer.elementhandle.isvisible/"target="_blank"rel="noopener noreferrer">visible</a> or hidden.</li>
<li>Waits for the element to become enabled.</li>
<li>Waits for the element to have a stable bounding box over two consecutive
animation frames.</li>
</ul>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="clicking-an-element-matching-a-criteria">Clicking an element matching a criteria<ahref="#clicking-an-element-matching-a-criteria"class="hash-link"aria-label="Direct link to Clicking an element matching a criteria"title="Direct link to Clicking an element matching a criteria"></a></h4>
<p>The following preconditions are automatically checked:</p>
<ul>
<li>Ensures the element is in the viewport.</li>
<li>Waits for the element to become
<ahref="https://pptr.dev/api/puppeteer.elementhandle.isvisible/"target="_blank"rel="noopener noreferrer">visible</a> or hidden.</li>
<li>Waits for the element to become enabled.</li>
<li>Waits for the element to have a stable bounding box over two consecutive
animation frames.</li>
</ul>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="filling-out-an-input">Filling out an input<ahref="#filling-out-an-input"class="hash-link"aria-label="Direct link to Filling out an input"title="Direct link to Filling out an input"></a></h4>
<p>Automatically detects the input type and choose an appropriate way to fill it out with the provided value.</p>
<p>The following preconditions are automatically checked:</p>
<ul>
<li>Ensures the element is in the viewport.</li>
<li>Waits for the element to become
<ahref="https://pptr.dev/api/puppeteer.elementhandle.isvisible/"target="_blank"rel="noopener noreferrer">visible</a> or hidden.</li>
<li>Waits for the element to become enabled.</li>
<li>Waits for the element to have a stable bounding box over two consecutive
animation frames.</li>
</ul>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="retrieving-an-element-property">Retrieving an element property<ahref="#retrieving-an-element-property"class="hash-link"aria-label="Direct link to Retrieving an element property"title="Direct link to Retrieving an element property"></a></h4>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="hover-over-an-element">Hover over an element<ahref="#hover-over-an-element"class="hash-link"aria-label="Direct link to Hover over an element"title="Direct link to Hover over an element"></a></h4>
<p>The following preconditions are automatically checked:</p>
<ul>
<li>Ensures the element is in the viewport.</li>
<li>Waits for the element to become
<ahref="https://pptr.dev/api/puppeteer.elementhandle.isvisible/"target="_blank"rel="noopener noreferrer">visible</a> or hidden.</li>
<li>Waits for the element to have a stable bounding box over two consecutive
animation frames.</li>
</ul>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="scroll-an-element">Scroll an element<ahref="#scroll-an-element"class="hash-link"aria-label="Direct link to Scroll an element"title="Direct link to Scroll an element"></a></h4>
<p>The following preconditions are automatically checked:</p>
<ul>
<li>Ensures the element is in the viewport.</li>
<li>Waits for the element to become
<ahref="https://pptr.dev/api/puppeteer.elementhandle.isvisible/"target="_blank"rel="noopener noreferrer">visible</a> or hidden.</li>
<li>Waits for the element to have a stable bounding box over two consecutive
animation frames.</li>
</ul>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="configuring-locators">Configuring locators<ahref="#configuring-locators"class="hash-link"aria-label="Direct link to Configuring locators"title="Direct link to Configuring locators"></a></h3>
<p>Locators can be configured to tune configure the preconditions and other other options:</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="getting-locator-events">Getting locator events<ahref="#getting-locator-events"class="hash-link"aria-label="Direct link to Getting locator events"title="Direct link to Getting locator events"></a></h3>
<p>Currently, locators support a single event that notifies you when the locator is about to perform the action:</p>
<p>This event can be used for logging/debugging or other purposes. The event might
fire multiple times if the locator retries the action.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="query-selectors">Query Selectors<ahref="#query-selectors"class="hash-link"aria-label="Direct link to Query Selectors"title="Direct link to Query Selectors"></a></h2>
<p>Queries are the primary mechanism for interacting with the DOM on your site. For example, a typical workflow goes like:</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="p-selectors"><code>P</code> Selectors<ahref="#p-selectors"class="hash-link"aria-label="Direct link to p-selectors"title="Direct link to p-selectors"></a></h3>
<p>Puppeteer uses a superset of the CSS selector syntax for querying. We call this syntax <em>P selectors</em> and it's supercharged with extra capabilities such as deep combinators and text selection.</p>
<divclass="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><divclass="admonitionHeading_Gvgb"><spanclass="admonitionIcon_Rf37"><svgviewBox="0 0 16 16"><pathfill-rule="evenodd"d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>caution</div><divclass="admonitionContent_BuS1"><p>Although P selectors look like real CSS selectors (we intentionally designed it this way), they should not be used for actually CSS styling. They are designed only for Puppeteer.</p></div></div>
<divclass="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><divclass="admonitionHeading_Gvgb"><spanclass="admonitionIcon_Rf37"><svgviewBox="0 0 14 16"><pathfill-rule="evenodd"d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><divclass="admonitionContent_BuS1"><p>P selectors only work on the first "depth" of selectors; for example, <code>:is(div >>> a)</code> will not work.</p></div></div>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="-and--combinators"><code>>>></code> and <code>>>>></code> combinators<ahref="#-and--combinators"class="hash-link"aria-label="Direct link to -and--combinators"title="Direct link to -and--combinators"></a></h4>
<p>The <code>>>></code> and <code>>>>></code> are called <em>deep descendent</em> and <em>deep</em> combinators respectively. Both combinators have the effect of going into shadow hosts with <code>>>></code> going into every shadow host under a node and <code>>>>></code> going into the immediate one (if the node is a shadow host; otherwise, it's a no-op).</p>
<divclass="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><divclass="admonitionHeading_Gvgb"><spanclass="admonitionIcon_Rf37"><svgviewBox="0 0 14 16"><pathfill-rule="evenodd"d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><divclass="admonitionContent_BuS1"><p>A common question is when should <code>>>>></code> be chosen over <code>>>></code> considering the flexibility of <code>>>></code>. A similar question can be asked about <code>></code> and a space; choose <code>></code> if you do not need to query all elements under a given node and a space otherwise. This answer extends to <code>>>>></code> (<code>></code>) and <code>>>></code> (space) naturally.</p></div></div>
<h5class="anchor anchorWithStickyNavbar_LWe7"id="example">Example<ahref="#example"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h5>
<p>Suppose we have the markup</p>
<divclass="language-html codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-html codeBlock_bY9V thin-scrollbar"style="color:#393A34;background-color:#f6f8fa"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token tag punctuation"style="color:#393A34"><</span><spanclass="token tag"style="color:#00009f">custom-element</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token tag punctuation"style="color:#393A34"><</span><spanclass="token tag"style="color:#00009f">template</span><spanclass="token tag"style="color:#00009f"></span><spanclass="token tag attr-name"style="color:#00a4db">shadowrootmode</span><spanclass="token tag attr-value punctuation attr-equals"style="color:#393A34">=</span><spanclass="token tag attr-value punctuation"style="color:#393A34">"</span><spanclass="token tag attr-value"style="color:#e3116c">open</span><spanclass="token tag attr-value punctuation"style="color:#393A34">"</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token tag punctuation"style="color:#393A34"><</span><spanclass="token tag"style="color:#00009f">slot</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token tag punctuation"style="color:#393A34"></</span><spanclass="token tag"style="color:#00009f">slot</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token tag punctuation"style="color:#393A34"></</span><spanclass="token tag"style="color:#00009f">template</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token tag punctuation"style="color:#393A34"><</span><spanclass="token tag"style="color:#00009f">custom-element</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token tag punctuation"style="color:#393A34"><</span><spanclass="token tag"style="color:#00009f">template</span><spanclass="token tag"style="color:#00009f"></span><spanclass="token tag attr-name"style="color:#00a4db">shadowrootmode</span><spanclass="token tag attr-value punctuation attr-equals"style="color:#393A34">=</span><spanclass="token tag attr-value punctuation"style="color:#393A34">"</span><spanclass="token tag attr-value"style="color:#e3116c">open</span><spanclass="token tag attr-value punctuation"style="color:#393A34">"</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token tag punctuation"style="color:#393A34"><</span><spanclass="token tag"style="color:#00009f">slot</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token tag punctuation"style="color:#393A34"></</span><spanclass="token tag"style="color:#00009f">slot</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token tag punctuation"style="color:#393A34"></</span><spanclass="token tag"style="color:#00009f">template</span><sp
<blockquote>
<p>Note: <code><template shadowrootmode="open"></code> is not supported on Firefox.
You can read more about it <ahref="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template#attributes"target="_blank"rel="noopener noreferrer">here</a>.</p>
</blockquote>
<p>Then <code>custom-element >>> h2</code> will return <code>h2</code>, but <code>custom-element >>>> h2</code> will return nothing since the inner <code>h2</code> is in a deeper shadow root.</p>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="p-elements"><code>P</code>-elements<ahref="#p-elements"class="hash-link"aria-label="Direct link to p-elements"title="Direct link to p-elements"></a></h4>
<p><code>P</code> elements are <ahref="https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-elements"target="_blank"rel="noopener noreferrer">pseudo-elements</a> with a <code>-p</code> vendor prefix. It allows you to enhance your selectors with Puppeteer-specific query engines such as XPath, text queries, and ARIA.</p>
<h5class="anchor anchorWithStickyNavbar_LWe7"id="text-selectors--p-text">Text selectors (<code>-p-text</code>)<ahref="#text-selectors--p-text"class="hash-link"aria-label="Direct link to text-selectors--p-text"title="Direct link to text-selectors--p-text"></a></h5>
<p>Text selectors will select "minimal" elements containing the given text, even within (open) shadow roots. Here, "minimum" means the deepest elements that contain a given text, but not their parents (which technically will also contain the given text).</p>
<h6class="anchor anchorWithStickyNavbar_LWe7"id="example-1">Example<ahref="#example-1"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h6>
<divclass="language-ts codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-ts codeBlock_bY9V thin-scrollbar"style="color:#393A34;background-color:#f6f8fa"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token keyword"style="color:#00009f">const</span><spanclass="token plain"> element </span><spanclass="token operator"style="color:#393A34">=</span><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">await</span><spanclass="token plain"> page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">waitForSelector</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'div ::-p-text(My name is Jun)'</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token comment"style="color:#999988;font-style:italic">// You can also use escapes.</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">const</span><spanclass="token plain"> element </span><spanclass="token operator"style="color:#393A34">=</span><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">await</span><spanclass="token plain"> page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">waitForSelector</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token string"style="color:#e3116c">':scope >>> ::-p-text(My name is Jun \\(pronounced like "June"\\))'</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token comment"style="color:#999988;font-style:italic">// or quotes</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">const</span><spanclass="token plain"> element </span><spanclass="token operator"style="color:#393A34">=</span><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">await</span><spanclass="token plain"> page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">waitForSelector</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token string"style="color:#e3116c">'div >>>> ::-p-text("My name is Jun (pronounced like \\"June\\")"):hover'</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="cu
<h5class="anchor anchorWithStickyNavbar_LWe7"id="xpath-selectors--p-xpath">XPath selectors (<code>-p-xpath</code>)<ahref="#xpath-selectors--p-xpath"class="hash-link"aria-label="Direct link to xpath-selectors--p-xpath"title="Direct link to xpath-selectors--p-xpath"></a></h5>
<p>XPath selectors will use the browser's native <ahref="https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate"target="_blank"rel="noopener noreferrer"><code>Document.evaluate</code></a> to query for elements.</p>
<h6class="anchor anchorWithStickyNavbar_LWe7"id="example-2">Example<ahref="#example-2"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h6>
<h5class="anchor anchorWithStickyNavbar_LWe7"id="aria-selectors--p-aria">ARIA selectors (<code>-p-aria</code>)<ahref="#aria-selectors--p-aria"class="hash-link"aria-label="Direct link to aria-selectors--p-aria"title="Direct link to aria-selectors--p-aria"></a></h5>
<p>ARIA selectors can be used to find elements with a given ARIA label. These labels are computed using Chrome's internal representation.</p>
<h6class="anchor anchorWithStickyNavbar_LWe7"id="example-3">Example<ahref="#example-3"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h6>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="custom-selectors">Custom selectors<ahref="#custom-selectors"class="hash-link"aria-label="Direct link to Custom selectors"title="Direct link to Custom selectors"></a></h4>
<p>Puppeteer provides users the ability to add their own query selectors to Puppeteer using <ahref="/next/api/puppeteer.registercustomqueryhandler">Puppeteer.registerCustomQueryHandler</a>. This is useful for creating custom selectors based on framework objects or other vendor-specific objects.</p>
<h5class="anchor anchorWithStickyNavbar_LWe7"id="custom-selectors-1">Custom Selectors<ahref="#custom-selectors-1"class="hash-link"aria-label="Direct link to Custom Selectors"title="Direct link to Custom Selectors"></a></h5>
<p>You can register a custom query handler that allows you to create custom selectors. For example, define a query handler for <code>getById</code> selectors:</p>
<h5class="anchor anchorWithStickyNavbar_LWe7"id="custom-framework-components-selector">Custom framework components selector<ahref="#custom-framework-components-selector"class="hash-link"aria-label="Direct link to Custom framework components selector"title="Direct link to Custom framework components selector"></a></h5>
<divclass="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><divclass="admonitionHeading_Gvgb"><spanclass="admonitionIcon_Rf37"><svgviewBox="0 0 16 16"><pathfill-rule="evenodd"d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>caution</div><divclass="admonitionContent_BuS1"><p>Be careful when relying on internal APIs of libraries or frameworks. They can change at any time.</p></div></div>
<p>Find Vue components by name by using Vue internals for querying:</p>
<h5class="anchor anchorWithStickyNavbar_LWe7"id="web-components">Web Components<ahref="#web-components"class="hash-link"aria-label="Direct link to Web Components"title="Direct link to Web Components"></a></h5>
<p>Web Components create their own tag so you can query them by the tag name:</p>
<p>Extend <code>HTMLElementTagNameMap</code> to define types for custom tags. This allows Puppeteer to infer the return type for the ElementHandle:</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="query-selectors-legacy">Query Selectors (legacy)<ahref="#query-selectors-legacy"class="hash-link"aria-label="Direct link to Query Selectors (legacy)"title="Direct link to Query Selectors (legacy)"></a></h2>
<divclass="theme-admonition theme-admonition-caution admonition_xJq3 alert alert--warning"><divclass="admonitionHeading_Gvgb"><spanclass="admonitionIcon_Rf37"><svgviewBox="0 0 16 16"><pathfill-rule="evenodd"d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>caution</div><divclass="admonitionContent_BuS1"><p>While we maintin prefixed selectors, the recommended way is to use the selector syntax documented above.</p></div></div>
<p>Queries are the primary mechanism for interacting with the DOM on your site. For example, a typical workflow goes like:</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="css">CSS<ahref="#css"class="hash-link"aria-label="Direct link to CSS"title="Direct link to CSS"></a></h3>
<p>CSS selectors follow the CSS spec of the browser being automated. We provide some basic type deduction for CSS selectors (such as <code>HTMLInputElement</code> for <code>input</code>), but any selector that contains no type information (such as <code>.class-name</code>) will need to be coerced manually using TypeScript's <code>as</code> coercion mechanism.</p>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="example-4">Example<ahref="#example-4"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h4>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="built-in-selectors">Built-in selectors<ahref="#built-in-selectors"class="hash-link"aria-label="Direct link to Built-in selectors"title="Direct link to Built-in selectors"></a></h3>
<p>Built-in selectors are Puppeteer's own class of selectors for doing things CSS cannot. Every built-in selector starts with a prefix <code>.../</code> to assist Puppeteer in distinguishing between CSS selectors and a built-in.</p>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="text-selectors-text">Text selectors (<code>text/</code>)<ahref="#text-selectors-text"class="hash-link"aria-label="Direct link to text-selectors-text"title="Direct link to text-selectors-text"></a></h4>
<p>Text selectors will select "minimal" elements containing the given text, even within (open) shadow roots. Here, "minimum" means the deepest elements that contain a given text, but not their parents (which technically will also contain the given text).</p>
<h5class="anchor anchorWithStickyNavbar_LWe7"id="example-5">Example<ahref="#example-5"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h5>
<divclass="language-ts codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-ts codeBlock_bY9V thin-scrollbar"style="color:#393A34;background-color:#f6f8fa"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token comment"style="color:#999988;font-style:italic">// Note we usually need type coercion since the type cannot be deduced, but for text selectors, `instanceof` checks may be better for runtime validation.</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">const</span><spanclass="token plain"> element </span><spanclass="token operator"style="color:#393A34">=</span><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">await</span><spanclass="token plain"> page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">waitForSelector</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'text/My name is Jun'</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="xpath-selectors-xpath">XPath selectors (<code>xpath/</code>)<ahref="#xpath-selectors-xpath"class="hash-link"aria-label="Direct link to xpath-selectors-xpath"title="Direct link to xpath-selectors-xpath"></a></h4>
<p>XPath selectors will use the browser's native <ahref="https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate"target="_blank"rel="noopener noreferrer"><code>Document.evaluate</code></a> to query for elements.</p>
<h5class="anchor anchorWithStickyNavbar_LWe7"id="example-6">Example<ahref="#example-6"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h5>
<divclass="language-ts codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-ts codeBlock_bY9V thin-scrollbar"style="color:#393A34;background-color:#f6f8fa"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token comment"style="color:#999988;font-style:italic">// There is not type deduction for XPaths.</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">const</span><spanclass="token plain"> node </span><spanclass="token operator"style="color:#393A34">=</span><spanclass="token plain"></span><spanclass="token keyword"style="color:#00009f">await</span><spanclass="token plain"> page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">waitForSelector</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'xpath/h2'</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="aria-selectors-aria">ARIA selectors (<code>aria/</code>)<ahref="#aria-selectors-aria"class="hash-link"aria-label="Direct link to aria-selectors-aria"title="Direct link to aria-selectors-aria"></a></h4>
<p>ARIA selectors can be used to find elements with a given ARIA label. These labels are computed using Chrome's internal representation.</p>
<h5class="anchor anchorWithStickyNavbar_LWe7"id="example-7">Example<ahref="#example-7"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h5>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="pierce-selectors-pierce">Pierce selectors (<code>pierce/</code>)<ahref="#pierce-selectors-pierce"class="hash-link"aria-label="Direct link to pierce-selectors-pierce"title="Direct link to pierce-selectors-pierce"></a></h4>
<p>Pierce selectors will run the <code>querySelector*</code> API on the document and all shadow roots to find an element.</p>
<h5class="anchor anchorWithStickyNavbar_LWe7"id="example-8">Example<ahref="#example-8"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h5>
<p>Suppose the HTML is</p>
<divclass="language-html codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-html codeBlock_bY9V thin-scrollbar"style="color:#393A34;background-color:#f6f8fa"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token tag punctuation"style="color:#393A34"><</span><spanclass="token tag"style="color:#00009f">div</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token tag punctuation"style="color:#393A34"><</span><spanclass="token tag"style="color:#00009f">custom-element</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token tag punctuation"style="color:#393A34"><</span><spanclass="token tag"style="color:#00009f">div</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token tag punctuation"style="color:#393A34"></</span><spanclass="token tag"style="color:#00009f">div</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token tag punctuation"style="color:#393A34"></</span><spanclass="token tag"style="color:#00009f">custom-element</span><spanclass="token tag punctuation"style="color:#393A34">></span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token tag punctuation"style="color:#393A34"></</span><spanclass="token tag"style="color:#00009f">div</span><spanclass="token tag punctuation"style="color:#393A34">></span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div>
<p>Then</p>
<divclass="language-ts codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-ts codeBlock_bY9V thin-scrollbar"style="color:#393A34;background-color:#f6f8fa"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><spanclass="token comment"style="color:#999988;font-style:italic">// This will be two elements because of the outer and inner div.</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token function"style="color:#d73a49">expect</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token keyword"style="color:#00009f">await</span><spanclass="token plain"> page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">$$</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'pierce/div'</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token plain">length</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">toBe</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token number"style="color:#36acaa">2</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"style="display:inline-block"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token comment"style="color:#999988;font-style:italic">// Partial piercing doesn't work.</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"></span><spanclass="token function"style="color:#d73a49">expect</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token keyword"style="color:#00009f">await</span><spanclass="token plain"> page</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">$$</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'pierce/div div'</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token plain">length</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">toBe</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token number"style="color:#36acaa">0</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">;</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path
<h3class="anchor anchorWithStickyNavbar_LWe7"id="custom-selectors-2">Custom selectors<ahref="#custom-selectors-2"class="hash-link"aria-label="Direct link to Custom selectors"title="Direct link to Custom selectors"></a></h3>
