Table of Contents

Interface IElementHandle

Namespace
PuppeteerSharp
Assembly
PuppeteerSharp.dll

Inherits from IJSHandle. It represents an in-page DOM element. ElementHandles can be created by QuerySelectorAsync(string) or QuerySelectorAllAsync(string).

public interface IElementHandle : IJSHandle, IAsyncDisposable
Extension Methods

Properties

Frame

Parent frame.

IFrame Frame { get; }

Property Value

IFrame

Methods

BoundingBoxAsync()

This method returns the bounding box of the element (relative to the main frame), or null if the element is not visible.

Task<BoundingBox> BoundingBoxAsync()

Returns

Task<BoundingBox>

The BoundingBox task.

BoxModelAsync()

returns boxes of the element, or null if the element is not visible. Box points are sorted clock-wise.

Task<BoxModel> BoxModelAsync()

Returns

Task<BoxModel>

Task BoxModel task.

ClickAsync(ClickOptions)

Scrolls element into view if needed, and then uses Mouse to click in the center of the element.

Task ClickAsync(ClickOptions options = null)

Parameters

options ClickOptions

click options.

Returns

Task

Task which resolves when the element is successfully clicked.

Exceptions

PuppeteerException

if the element is detached from DOM.

ClickablePointAsync(Offset?)

Returns the middle point within an element unless a specific offset is provided.

Task<BoxModelPoint> ClickablePointAsync(Offset? offset = null)

Parameters

offset Offset?

Optional offset.

Returns

Task<BoxModelPoint>

A Task that resolves to the clickable point.

Exceptions

PuppeteerException

When the node is not visible or not an HTMLElement.

ContentFrameAsync()

Resolves the frame associated with the element..

Task<IFrame> ContentFrameAsync()

Returns

Task<IFrame>

Task which resolves to the frame associated with the element.

DragAndDropAsync(IElementHandle, int)

Performs a drag, dragenter, dragover, and drop in sequence.

Task DragAndDropAsync(IElementHandle target, int delay = 0)

Parameters

target IElementHandle

Target element.

delay int

If specified, is the time to wait between dragover and drop in milliseconds.

Returns

Task

A Task that resolves when the message was confirmed by the browser.

DragAsync(IElementHandle)

This method creates and captures a dragevent from the element.

[Obsolete("Just use DropAsync instead")]
Task<DragData> DragAsync(IElementHandle target)

Parameters

target IElementHandle

Target Element.

Returns

Task<DragData>

A Task that resolves when the message was confirmed by the browser with the drag data.

DragAsync(decimal, decimal)

This method creates and captures a dragevent from the element.

[Obsolete("Just use DropAsync instead")]
Task<DragData> DragAsync(decimal x, decimal y)

Parameters

x decimal

X coordinate.

y decimal

Y coordinate.

Returns

Task<DragData>

A Task that resolves when the message was confirmed by the browser with the drag data.

DragEnterAsync(DragData)

Dispatches a dragenter event.

[Obsolete("Don't useDragEnterAsync. `dragenter` will automatically be performed during dragging. ")]
Task DragEnterAsync(DragData data)

Parameters

data DragData

Drag data containing items and operations mask.

Returns

Task

A Task that resolves when the message was confirmed by the browser.

DragOverAsync(DragData)

Dispatches a dragover event.

[Obsolete("Don't useDragOverAsync. `dragover` will automatically be performed during dragging. ")]
Task DragOverAsync(DragData data)

Parameters

data DragData

Drag data containing items and operations mask.

Returns

Task

A Task that resolves when the message was confirmed by the browser.

DropAsync(DragData)

Performs a dragenter, dragover, and drop in sequence.

Task DropAsync(DragData data)

Parameters

data DragData

Drag data containing items and operations mask.

Returns

Task

A Task that resolves when the message was confirmed by the browser.

DropAsync(IElementHandle)

Performs a dragenter, dragover, and drop in sequence.

Task DropAsync(IElementHandle element)

Parameters

element IElementHandle

Element to drop.

Returns

Task

A Task that resolves when the message was confirmed by the browser.

FocusAsync()

Calls focus https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus on the element.

Task FocusAsync()

Returns

Task

Task.

HoverAsync()

Scrolls element into view if needed, and then uses Mouse to hover over the center of the element.

Task HoverAsync()

Returns

Task

Task which resolves when the element is successfully hovered.

IsHiddenAsync()

Checks if an element is hidden using the same mechanism as WaitForSelectorAsync(string, WaitForSelectorOptions).

Task<bool> IsHiddenAsync()

Returns

Task<bool>

Task which resolves to true if the element is hidden.

IsIntersectingViewportAsync(decimal)

Evaluates 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.

Task<bool> IsIntersectingViewportAsync(decimal threshold = 0)

Parameters

threshold decimal

A number between 0 and 1 specifying the fraction of the element's area that must be visible to pass the check.

Returns

Task<bool>

A task which resolves to true if the element is visible in the current viewport.

IsVisibleAsync()

Checks if an element is visible using the same mechanism as WaitForSelectorAsync(string, WaitForSelectorOptions).

Task<bool> IsVisibleAsync()

Returns

Task<bool>

Task which resolves to true if the element is visible.

PressAsync(string, PressOptions)

Focuses the element, and then uses DownAsync(string, DownOptions) and UpAsync(string).

Task PressAsync(string key, PressOptions options = null)

Parameters

key string

Name of key to press, such as ArrowLeft. See KeyDefinitions for a list of all key names.

options PressOptions

press options.

Returns

Task

Task which resolves when the key is successfully pressed.

Remarks

If key is a single character and no modifier keys besides Shift are being held down, a keypress/input event will also be generated. The Text option can be specified to force an input event to be generated.

QuerySelectorAllAsync(string)

Runs element.querySelectorAll within the page. If no elements match the selector, the return value resolve to Empty<T>().

Task<IElementHandle[]> QuerySelectorAllAsync(string selector)

Parameters

selector string

A selector to query element for.

Returns

Task<IElementHandle[]>

Task which resolves to ElementHandles pointing to the frame elements.

QuerySelectorAllHandleAsync(string)

A utility function to be used with EvaluateFunctionAsync<T>(Task<IJSHandle>, string, params object[]).

Task<IJSHandle> QuerySelectorAllHandleAsync(string selector)

Parameters

selector string

A selector to query element for.

Returns

Task<IJSHandle>

Task which resolves to a IJSHandle of document.querySelectorAll result.

QuerySelectorAsync(string)

The method runs element.querySelector within the page. If no element matches the selector, the return value resolve to null.

Task<IElementHandle> QuerySelectorAsync(string selector)

Parameters

selector string

A selector to query element for.

Returns

Task<IElementHandle>

Task which resolves to IElementHandle pointing to the frame element.

ScreenshotAsync(string)

This method scrolls element into view if needed, and then uses ScreenshotAsync(string) to take a screenshot of the element. If the element is detached from DOM, the method throws an error.

Task ScreenshotAsync(string file)

Parameters

file string

The file path to save the image to. The screenshot type will be inferred from file extension. If path is a relative path, then it is resolved relative to current working directory. If no path is provided, the image won't be saved to the disk.

Returns

Task

The task.

ScreenshotAsync(string, ElementScreenshotOptions)

This method scrolls element into view if needed, and then uses ScreenshotDataAsync(ScreenshotOptions) to take a screenshot of the element. If the element is detached from DOM, the method throws an error.

Task ScreenshotAsync(string file, ElementScreenshotOptions options)

Parameters

file string

The file path to save the image to. The screenshot type will be inferred from file extension. If path is a relative path, then it is resolved relative to current working directory. If no path is provided, the image won't be saved to the disk.

options ElementScreenshotOptions

Screenshot options.

Returns

Task

The task.

ScreenshotBase64Async()

This method scrolls element into view if needed, and then uses ScreenshotBase64Async(ScreenshotOptions) to take a screenshot of the element. If the element is detached from DOM, the method throws an error.

Task<string> ScreenshotBase64Async()

Returns

Task<string>

Task which resolves to a string containing the image data as base64.

ScreenshotBase64Async(ElementScreenshotOptions)

This method scrolls element into view if needed, and then uses ScreenshotBase64Async(ScreenshotOptions) to take a screenshot of the element. If the element is detached from DOM, the method throws an error.

Task<string> ScreenshotBase64Async(ElementScreenshotOptions options)

Parameters

options ElementScreenshotOptions

Screenshot options.

Returns

Task<string>

Task which resolves to a string containing the image data as base64.

ScreenshotDataAsync()

This method scrolls element into view if needed, and then uses ScreenshotDataAsync(ScreenshotOptions) to take a screenshot of the element. If the element is detached from DOM, the method throws an error.

Task<byte[]> ScreenshotDataAsync()

Returns

Task<byte[]>

Task which resolves to a byte[] containing the image data.

ScreenshotDataAsync(ElementScreenshotOptions)

This method scrolls element into view if needed, and then uses ScreenshotDataAsync(ScreenshotOptions) to take a screenshot of the element. If the element is detached from DOM, the method throws an error.

Task<byte[]> ScreenshotDataAsync(ElementScreenshotOptions options)

Parameters

options ElementScreenshotOptions

Screenshot options.

Returns

Task<byte[]>

Task which resolves to a byte[] containing the image data.

ScreenshotStreamAsync()

This method scrolls element into view if needed, and then uses ScreenshotDataAsync(ScreenshotOptions) to take a screenshot of the element. If the element is detached from DOM, the method throws an error.

Task<Stream> ScreenshotStreamAsync()

Returns

Task<Stream>

Task which resolves to a Stream containing the image data.

ScreenshotStreamAsync(ElementScreenshotOptions)

This method scrolls element into view if needed, and then uses ScreenshotDataAsync(ScreenshotOptions) to take a screenshot of the element. If the element is detached from DOM, the method throws an error.

Task<Stream> ScreenshotStreamAsync(ElementScreenshotOptions options)

Parameters

options ElementScreenshotOptions

Screenshot options.

Returns

Task<Stream>

Task which resolves to a Stream containing the image data.

ScrollIntoViewAsync()

Scrolls the element into view using either the automation protocol client or by calling element.scrollIntoView.

Task ScrollIntoViewAsync()

Returns

Task

A Task that resolves when the message was confirmed by the browser.

SelectAsync(params string[])

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 exception.

Task<string[]> SelectAsync(params string[] values)

Parameters

values string[]

Values of options to select. If the select has the multiple attribute, all values are considered, otherwise only the first one is taken into account.

Returns

Task<string[]>

A task that resolves to an array of option values that have been successfully selected.

Examples

await handle.SelectAsync("blue"); // single selection
await handle.SelectAsync("red", "green", "blue"); // multiple selections

TapAsync()

Scrolls element into view if needed, and then uses TapAsync(decimal, decimal) to tap in the center of the element.

Task TapAsync()

Returns

Task

Task which resolves when the element is successfully tapped.

Exceptions

PuppeteerException

if the element is detached from DOM.

TouchEndAsync()

/// Dispatches a touchendt event.

Task TouchEndAsync()

Returns

Task

A Task that resolves when the message was confirmed by the browser.

TouchMoveAsync()

Dispatches a touchmove event.

Task TouchMoveAsync()

Returns

Task

A Task that resolves when the message was confirmed by the browser.

TouchStartAsync()

Dispatches a touchstart event.

Task TouchStartAsync()

Returns

Task

A Task that resolves when the message was confirmed by the browser.

TypeAsync(string, TypeOptions)

Focuses the element, and sends a keydown, keypress/input, and keyup event for each character in the text.

Task TypeAsync(string text, TypeOptions options = null)

Parameters

text string

A text to type into a focused element.

options TypeOptions

type options.

Returns

Task

Task.

Examples

elementHandle.TypeAsync("#mytextarea", "Hello"); // Types instantly
elementHandle.TypeAsync("#mytextarea", "World", new TypeOptions { Delay = 100 }); // Types slower, like a user

An example of typing into a text field and then submitting the form:

var elementHandle = await page.GetElementAsync("input");
await elementHandle.TypeAsync("some text");
await elementHandle.PressAsync("Enter");

Remarks

To press a special key, like Control or ArrowDown use PressAsync(string, PressOptions).

UploadFileAsync(bool, params string[])

Uploads files.

Task UploadFileAsync(bool resolveFilePaths, params string[] filePaths)

Parameters

resolveFilePaths bool

Set to true to resolve paths using GetFullPath(string).

filePaths string[]

Sets the value of the file input to these paths. Paths are resolved using GetFullPath(string).

Returns

Task

Task.

Remarks

This method expects elementHandle to point to an input element https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input.

UploadFileAsync(params string[])

Uploads files.

Task UploadFileAsync(params string[] filePaths)

Parameters

filePaths string[]

Sets the value of the file input to these paths. Paths are resolved using GetFullPath(string).

Returns

Task

Task.

Remarks

This method expects elementHandle to point to an input element https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input.

WaitForSelectorAsync(string, WaitForSelectorOptions)

Waits for a selector to be added to the DOM.

Task<IElementHandle> WaitForSelectorAsync(string selector, WaitForSelectorOptions options = null)

Parameters

selector string

A selector of an element to wait for.

options WaitForSelectorOptions

Optional waiting parameters.

Returns

Task<IElementHandle>

A task that resolves when element specified by selector string is added to DOM. Resolves to null if waiting for hidden: true and selector is not found in DOM.

XPathAsync(string)

Evaluates the XPath expression relative to the elementHandle. If there's no such element, the method will resolve to null.

[Obsolete("Use QuerySelectorAsync instead")]
Task<IElementHandle[]> XPathAsync(string expression)

Parameters

expression string

Expression to evaluate https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate.

Returns

Task<IElementHandle[]>

Task which resolves to an array of IElementHandle.

Request doc improvement