<titledata-rh="true">Locators | 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/locators"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docsearch:counter"content="3"><metadata-rh="true"property="og:title"content="Locators | Puppeteer"><metadata-rh="true"name="description"content="Locators is a new experimental API that combines waitForSelector and element"><metadata-rh="true"property="og:description"content="Locators is a new experimental API that combines waitForSelector and element"><linkdata-rh="true"rel="icon"href="/img/favicon.ico"><linkdata-rh="true"rel="canonical"href="https://pptr.dev/next/guides/locators"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/next/guides/locators"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://pptr.dev/next/guides/locators"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">
in the Locators API.</p></div></div><h2class="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></h2><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"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><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">locator</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'button'</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">click</span><spanclass="token punctuation"style="color:#393A34">(</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><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><h2class="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></h2><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"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><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">locator</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'input'</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">fill</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'value'</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><p>Automatically detects the input type and choose an approritate 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><h2class="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></h2><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"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><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">locator</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'div'</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">hover</span><spanclass="token punctuation"style="color:#393A34">(</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><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><h2class="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></h2><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"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#393A34"><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">locator</span><spanclass="token punctuation"style="color:#393A34">(</span><spanclass="token string"style="color:#e3116c">'div'</span><spanclass="token punctuation"style="color:#393A34">)</span><spanclass="token punctuation"style="color:#393A34">.</span><spanclass="token function"style="color:#d73a49">scroll</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"> scrollLeft</span><spanclass="token operator"style="color:#393A34">:</span><spanclass="token plain"></span><spanclass="token number"style="color:#36acaa">10</span><spanclass="token punctuation"style="color:#393A34">,</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#393A34"><spanclass="token plain"> scrollTop</span><spanclass="token operator"style="color:#393A34">:</span><spanclass="token plain"></span><spanclass="token number"style="color:#36acaa">20</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 punctuation"style="color:#393A34">}</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><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