puppeteer/website/versioned_docs/version-21.9.0/api/puppeteer.elementhandle.md

sidebar_label
ElementHandle

ElementHandle class

ElementHandle represents an in-page DOM element.

Signature:

export declare abstract class ElementHandle<ElementType extends Node = Element> extends JSHandle<ElementType>

Extends: JSHandle<ElementType>

Remarks

ElementHandles can be created with the Page.$() method.

import puppeteer from 'puppeteer';

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  const hrefElement = await page.$('a');
  await hrefElement.click();
  // ...
})();

ElementHandle prevents the DOM element from being garbage-collected unless the handle is disposed. ElementHandles are auto-disposed when their origin frame gets navigated.

ElementHandle instances can be used as arguments in Page.$eval() and Page.evaluate() methods.

If you're using TypeScript, ElementHandle takes a generic argument that denotes the type of element the handle is holding within. For example, if you have a handle to a <select> element, you can type it as ElementHandle<HTMLSelectElement> and you get some nicer type checks.

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the ElementHandle class.

Properties

Property	Modifiers	Type	Description
frame	readonly	Frame	Frame corresponding to the current handle.

Methods

Method	Modifiers	Description
$		Queries the current element for an element matching the given selector.
$$		Queries the current element for all elements matching the given selector.
$$eval		Runs the given function on an array of elements matching the given selector in the current element. If the given function returns a promise, then this method will wait till the promise resolves.
$eval		Runs the given function on the first element matching the given selector in the current element. If the given function returns a promise, then this method will wait till the promise resolves.
$x
autofill		If the element is a form input, you can use ElementHandle.autofill() to test if the form is compatible with the browser's autofill implementation. Throws an error if the form cannot be autofilled.
boundingBox		This method returns the bounding box of the element (relative to the main frame), or null if the element is not part of the layout (example: display: none).
boxModel		This method returns boxes of the element, or null if the element is not part of the layout (example: display: none).
click		This method scrolls element into view if needed, and then uses Page.mouse to click in the center of the element. If the element is detached from DOM, the method throws an error.
clickablePoint		Returns the middle point within an element unless a specific offset is provided.
contentFrame		Resolves the frame associated with the element, if any. Always exists for HTMLIFrameElements.
contentFrame
drag		Drags an element over the given element or point.
dragAndDrop
dragEnter
dragOver
drop		Drops the given element onto the current one.
drop
focus		Calls focus on the element.
hover		This method scrolls element into view if needed, and then uses Page to hover over the center of the element. If the element is detached from DOM, the method throws an error.
isHidden		Checks if an element is hidden using the same mechanism as ElementHandle.waitForSelector().
isIntersectingViewport		Resolves to true if the element is visible in the current viewport. If an element is an SVG, we check if the svg owner element is in the viewport instead. See https://crbug.com/963246.
isVisible		Checks if an element is visible using the same mechanism as ElementHandle.waitForSelector().
press		Focuses the element, and then uses Keyboard.down() and Keyboard.up().
screenshot		This method scrolls element into view if needed, and then uses Page.screenshot() to take a screenshot of the element. If the element is detached from DOM, the method throws an error.
screenshot
scrollIntoView		Scrolls the element into view using either the automation protocol client or by calling element.scrollIntoView.
select		Triggers a change and input event once all the provided options have been selected. If there's no <select> element matching selector, the method throws an error.
tap		This method scrolls element into view if needed, and then uses Touchscreen.tap() to tap in the center of the element. If the element is detached from DOM, the method throws an error.
toElement		Converts the current handle to the given element type.
touchEnd
touchMove
touchStart
type		Focuses the element, and then sends a keydown, keypress/input, and keyup event for each character in the text. To press a special key, like Control or ArrowDown, use ElementHandle.press().
uploadFile		Sets the value of an input element to the given file paths.
waitForSelector		Wait for an element matching the given selector to appear in the current element. Unlike Frame.waitForSelector(), this method does not work across navigations or if the element is detached from DOM.
waitForXPath