<titledata-rh="true">Query Selectors (legacy) | 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-legacy"><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 (legacy) | 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-legacy"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/next/guides/query-selectors-legacy"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/next/guides/query-selectors-legacy"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="css">CSS<ahref="#css"class="hash-link"aria-label="Direct link to CSS"title="Direct link to CSS"></a></h2>
<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>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="example">Example<ahref="#example"class="hash-link"aria-label="Direct link to Example"title="Direct link to Example"></a></h3>
<h2class="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></h2>
<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>
<h3class="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></h3>
<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>
<h4class="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></h4>
<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>
<h3class="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></h3>
<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>
<h4class="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></h4>
<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>
<h3class="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></h3>
<p>ARIA selectors can be used to find elements with a given ARIA label. These labels are computed using Chrome's internal representation.</p>
<h4class="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></h4>
<h3class="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></h3>
<p>Pierce selectors will run the <code>querySelector*</code> API on the document and all shadow roots to find an element.</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>
<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
<h2class="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></h2>
