Table of Contents

Class ElementHandle

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 abstract class ElementHandle : JSHandle, IElementHandle, IJSHandle, IAsyncDisposable
Inheritance
ElementHandle
Implements
Derived
Extension Methods

Properties

Handle

Base handle.

protected JSHandle Handle { get; init; }

Property Value

JSHandle

Page

Element's page.

protected abstract Page Page { get; }

Property Value

Page

Methods

AssertConnectedElementAsync()

Checks whether the element is still connected to the browser.

protected Task AssertConnectedElementAsync()

Returns

Task

A Task representing the asynchronous operation.

Exceptions

PuppeteerException

The exception if the element is not connected.

BindIsolatedHandleAsync<TResult, TElementHandle>(Func<TElementHandle, Task<TResult>>)

Executes a function in the isolated context.

protected Task<TResult> BindIsolatedHandleAsync<TResult, TElementHandle>(Func<TElementHandle, Task<TResult>> action) where TElementHandle : ElementHandle

Parameters

action Func<TElementHandle, Task<TResult>>

Function to execute.

Returns

Task<TResult>

Task which resolves to the result of the function.

Type Parameters

TResult

Return type.

TElementHandle

Element handle type.

Exceptions

ArgumentNullException

Thrown if action is null.

BoundingBoxAsync()

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

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

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

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

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

public abstract 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.

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

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

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

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

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

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

public Task DropAsync(IElementHandle target)

Parameters

target IElementHandle

Returns

Task

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

FocusAsync()

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

public Task FocusAsync()

Returns

Task

Task.

GetPropertiesAsync()

Returns a Dictionary<TKey, TValue> with property names as keys and IJSHandle instances for the property values.

public override Task<Dictionary<string, IJSHandle>> GetPropertiesAsync()

Returns

Task<Dictionary<string, IJSHandle>>

Task which resolves to a Dictionary<TKey, TValue>.

Examples

var handle = await page.EvaluateExpressionHandle("({window, document})");
var properties = await handle.GetPropertiesAsync();
var windowHandle = properties["window"];
var documentHandle = properties["document"];
await handle.DisposeAsync();

GetPropertyAsync(string)

Fetches a single property from the referenced object.

public override Task<IJSHandle> GetPropertyAsync(string propertyName)

Parameters

propertyName string

property to get.

Returns

Task<IJSHandle>

Task of IJSHandle.

HoverAsync()

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

public 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).

public Task<bool> IsHiddenAsync()

Returns

Task<bool>

Task which resolves to true if the element is hidden.

IsIntersectingViewportAsync(int)

Evaluates if the element is visible in the current viewport.

public Task<bool> IsIntersectingViewportAsync(int threshold)

Parameters

threshold int

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

public Task<bool> IsVisibleAsync()

Returns

Task<bool>

Task which resolves to true if the element is visible.

JsonValueAsync<T>()

Returns a JSON representation of the object.

public override Task<T> JsonValueAsync<T>()

Returns

Task<T>

Task.

Type Parameters

T

A strongly typed object to parse to.

Remarks

The method will return an empty JSON if the referenced object is not stringifiable. It will throw an error if the object has circular references.

PressAsync(string, PressOptions)

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

public 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>().

public 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[]).

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

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

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

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

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

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

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

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

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

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

public virtual 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.

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

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

public Task TouchEndAsync()

Returns

Task

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

TouchMoveAsync()

Dispatches a touchmove event.

public Task TouchMoveAsync()

Returns

Task

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

TouchStartAsync()

Dispatches a touchstart event.

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

public 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

               <pre><code class="lang-csharp">elementHandle.TypeAsync("#mytextarea", "Hello"); // Types instantly
               elementHandle.TypeAsync("#mytextarea", "World", new TypeOptions { Delay = 100 }); // Types slower, like a user</code></pre>

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.

public abstract 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 elementhttps://developer.mozilla.org/en-US/docs/Web/HTML/Element/input.

UploadFileAsync(params string[])

Uploads files.

public 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 elementhttps://developer.mozilla.org/en-US/docs/Web/HTML/Element/input.

WaitForSelectorAsync(string, WaitForSelectorOptions)

Waits for a selector to be added to the DOM.

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

public 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