Class ElementHandle

A reference to a DOM element in the page, returned by Page.$, Page.$$, Frame.$, Frame.waitForSelector and the element members below. Everything on :class applies.

pjsc differences:

screenshot ignores path and always returns base64 text.
waitForSelector ends with the render; its signal option is ignored.
dragEnter / dragOver / drop refuse drag data that names files, and drag / dragAndDrop fail when the browser's drag data names files.
Not available: uploadFile and other members that read server files, $x (use the xpath/ selector prefix), and members that reach the browser, its pages or the raw protocol.

const link = await page.$("a.more");
const box = await link.boundingBox();
const png = await link.screenshot();
await link.click();

Hierarchy (View Summary)

JSHandle
- ElementHandle

Properties

`Readonly`frame

frame: Frame

The :class that holds the element.

Methods

$

$(selector: string): Promise<ElementHandle>
The first descendant matching selector, or null.
Parameters
- selector: string
Returns Promise<ElementHandle>

$$

$$(selector: string): Promise<ElementHandle[]>
Every descendant matching selector.
Parameters
- selector: string
Returns Promise<ElementHandle[]>

$$eval

$$eval(
    selector: string,
    pageFunction: PageFunction,
    ...args: any[],
): Promise<any>
Runs pageFunction(elements, ...args) on every descendant matching selector.
Parameters
- selector: string
- pageFunction: PageFunction
- ...args: any[]
Returns Promise<any>

$eval

$eval(
    selector: string,
    pageFunction: PageFunction,
    ...args: any[],
): Promise<any>
Runs pageFunction(element, ...args) on the first descendant matching selector.
Parameters
- selector: string
- pageFunction: PageFunction
- ...args: any[]
Returns Promise<any>

asElement

asElement(): ElementHandle

This handle as an :class when it references a DOM element, else null (synchronous).

Returns ElementHandle

Inherited from JSHandle.asElement

asLocator

asLocator(): Locator

Creates a :class for this element (synchronous).

Returns Locator

backendNodeId

backendNodeId(): Promise<number>

The element's Chrome DevTools backend node id.

Returns Promise<number>

boundingBox

boundingBox(): Promise<BoundingBox>

The element's bounding box in main-frame CSS pixels, or null when it is not rendered.

Returns Promise<BoundingBox>

boxModel

boxModel(): Promise<BoxModel>

The element's content, padding, border and margin boxes, or null when it is not rendered.

Returns Promise<BoxModel>

click

click(options?: ClickOptions & { offset?: Point }): Promise<void>
Scrolls the element into view and clicks it.
Parameters
- Optionaloptions: ClickOptions & { offset?: Point }
Returns Promise<void>

clickablePoint

clickablePoint(offset?: Point): Promise<Point>
A point in the element that a click would hit, in main-frame CSS pixels.
Parameters
- Optionaloffset: Point
Returns Promise<Point>

contentFrame

contentFrame(): Promise<Frame>

The :class shown by an <iframe> / <frame> element, else null.

Returns Promise<Frame>

dispose

dispose(): Promise<void>

Releases the handle. Disposing a disposed handle does nothing.

Returns Promise<void>

Inherited from JSHandle.dispose

drag

drag(target: ElementHandle | Point): Promise<void | DragData>
Drags from this element to target (a point or another element); returns the drag data when Page.setDragInterception is on.
Parameters
- target: ElementHandle | Point
Returns Promise<void | DragData>

dragAndDrop

dragAndDrop(target: ElementHandle, options?: { delay?: number }): Promise<void>
Drags this element and drops it on target.
Parameters
- target: ElementHandle
- Optionaloptions: { delay?: number }
  delay: milliseconds between dragover and drop
Returns Promise<void>

dragEnter

dragEnter(data?: DragData): Promise<void>
Dispatches dragenter on this element with data; drag data with files is refused.
Parameters
- Optionaldata: DragData
Returns Promise<void>

dragOver

dragOver(data?: DragData): Promise<void>
Dispatches dragover on this element with data; drag data with files is refused.
Parameters
- Optionaldata: DragData
Returns Promise<void>

drop

drop(dataOrElement?: DragData | ElementHandle): Promise<void>
Drops data (or the element being dragged) on this element; drag data with files is refused.
Parameters
- OptionaldataOrElement: DragData | ElementHandle
Returns Promise<void>

evaluate

evaluate(pageFunction: PageFunction, ...args: any[]): Promise<any>
Runs pageFunction(object, ...args) in the page and returns its result as JSON.
Parameters
- pageFunction: PageFunction
- ...args: any[]
Returns Promise<any>

Inherited from JSHandle.evaluate

evaluateHandle

evaluateHandle(pageFunction: PageFunction, ...args: any[]): Promise<JSHandle>
Runs pageFunction(object, ...args) in the page and returns its result as a :class.
Parameters
- pageFunction: PageFunction
- ...args: any[]
Returns Promise<JSHandle>

Inherited from JSHandle.evaluateHandle

focus

focus(): Promise<void>

Focuses the element.

Returns Promise<void>

getProperties

getProperties(): Promise<Map<string, JSHandle>>

The object's own enumerable properties, as a Map of name → :class.

Returns Promise<Map<string, JSHandle>>

Inherited from JSHandle.getProperties

getProperty

getProperty(propertyName: string): Promise<JSHandle>
The property propertyName of the object, as a :class.
Parameters
- propertyName: string
Returns Promise<JSHandle>

Inherited from JSHandle.getProperty

hover

hover(): Promise<void>

Scrolls the element into view and moves the mouse over it.

Returns Promise<void>

isHidden

isHidden(): Promise<boolean>

Whether the element is hidden.

Returns Promise<boolean>

isIntersectingViewport

isIntersectingViewport(options?: { threshold?: number }): Promise<boolean>
Whether the element intersects the viewport.
Parameters
- Optionaloptions: { threshold?: number }
Returns Promise<boolean>

isVisible

isVisible(): Promise<boolean>

Whether the element is visible.

Returns Promise<boolean>

jsonValue

jsonValue(): Promise<any>

The object as JSON (JSON.stringify in the page, then parsed); fails for objects that cannot be stringified.

Returns Promise<any>

Inherited from JSHandle.jsonValue

press

press(key: string, options?: { delay?: number; text?: string }): Promise<void>
Focuses the element and presses key (one key name, such as "Enter" or "ArrowLeft").
Parameters
- key: string
- Optionaloptions: { delay?: number; text?: string }
  delay between keydown and keyup, text
Returns Promise<void>

screenshot

screenshot(options?: ScreenshotOptions): Promise<string>
Scrolls the element into view and returns a screenshot of it as base64 text. path is ignored (no file is written) and encoding is always "base64".
Parameters
- Optionaloptions: ScreenshotOptions
  type ("png", "jpeg", "webp"), quality, omitBackground, clip, ...
Returns Promise<string>

scrollIntoView

scrollIntoView(): Promise<void>

Scrolls the element into view.

Returns Promise<void>

select

select(...values: string[]): Promise<string[]>
Selects values in a <select> element; returns the selected values.
Parameters
- ...values: string[]
Returns Promise<string[]>

tap

tap(): Promise<void>

Scrolls the element into view and taps it.

Returns Promise<void>

toElement

toElement(tagName: string): Promise<ElementHandle>
This handle when the element's tag is tagName (case-insensitive); fails otherwise.
Parameters
- tagName: string
Returns Promise<ElementHandle>

toString

toString(): string

A short description of the referenced object (synchronous).

Returns string

Inherited from JSHandle.toString

touchEnd

touchEnd(): Promise<void>

Scrolls the element into view and ends the first active touch. Fails when no touch is active.

Returns Promise<void>

touchMove

touchMove(touch?: TouchHandle): Promise<void>
Scrolls the element into view and moves touch (or, without it, the first active touch) to the element's center. Fails when no touch is active.
Parameters
- Optionaltouch: TouchHandle
Returns Promise<void>

touchStart

touchStart(): Promise<TouchHandle>

Scrolls the element into view and starts a touch at its center; returns the started :class.

Returns Promise<TouchHandle>

type

type(text: string, options?: { delay?: number }): Promise<void>
Focuses the element and types text.
Parameters
- text: string
- Optionaloptions: { delay?: number }
  delay between key presses in milliseconds
Returns Promise<void>

waitForSelector

waitForSelector(
selector: string,
options?: WaitForSelectorOptions,
): Promise<ElementHandle>
Waits for a descendant matching selector.
Parameters
- selector: string
- Optionaloptions: WaitForSelectorOptions
Returns Promise<ElementHandle>

Class ElementHandle

Hierarchy (View Summary)

Index

Properties

Methods

Properties

Readonlyframe

Methods

$

Parameters

Returns Promise<ElementHandle>

$$

Parameters

Returns Promise<ElementHandle[]>

$$eval

Parameters

Returns Promise<any>

$eval

Parameters

Returns Promise<any>

asElement

Returns ElementHandle

asLocator

Returns Locator

backendNodeId

Returns Promise<number>

boundingBox

Returns Promise<BoundingBox>

boxModel

Returns Promise<BoxModel>

click

Parameters

Returns Promise<void>

clickablePoint

Parameters

Returns Promise<Point>

contentFrame

Returns Promise<Frame>

dispose

Returns Promise<void>

drag

Parameters

Returns Promise<void | DragData>

dragAndDrop

Parameters

Returns Promise<void>

dragEnter

Parameters

Returns Promise<void>

dragOver

Parameters

Returns Promise<void>

drop

Parameters

Returns Promise<void>

evaluate

Parameters

Returns Promise<any>

evaluateHandle

Parameters

Returns Promise<JSHandle>

focus

Returns Promise<void>

getProperties

Returns Promise<Map<string, JSHandle>>

getProperty

Parameters

Returns Promise<JSHandle>

hover

Returns Promise<void>

isHidden

Returns Promise<boolean>

isIntersectingViewport

Parameters

Returns Promise<boolean>

isVisible

Returns Promise<boolean>

jsonValue

Returns Promise<any>

press

`Readonly`frame