<titledata-rh="true">Query Selectors | 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/query-selectors"><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="Query Selectors | Puppeteer"><metadata-rh="true"name="description"content="Queries are the primary mechanism for interacting with the DOM on your site. For example, a typical workflow goes like:"><metadata-rh="true"property="og:description"content="Queries are the primary mechanism for interacting with the DOM on your site. For example, a typical workflow goes like:"><linkdata-rh="true"rel="icon"href="/img/favicon.ico"><linkdata-rh="true"rel="canonical"href="https://pptr.dev/next/guides/query-selectors"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/next/guides/query-selectors"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/next/guides/query-selectors"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">
<h2class="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></h2>
<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>
<h3class="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></h3>
<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>
<h4class="anchor anchorWithStickyNavbar_LWe7"id="example">Example<ahref="#example"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h4>
<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>
<h3class="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></h3>
<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>
<h4class="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></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-1">Example<ahref="#example-1"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 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
<h4class="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></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-2">Example<ahref="#example-2"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h5>
<h4class="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></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-3">Example<ahref="#example-3"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h5>
<h3class="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></h3>
<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>
<h4class="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></h4>
<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>
<h4class="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></h4>
<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>
<h4class="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></h4>
<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>
