ElementHandle

Namespace: PuppeteerSharp

public abstract class ElementHandle : JSHandle, IElementHandle, IJSHandle, IAsyncDisposable

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

Inheritance: object → JSHandle

Implements: IElementHandle, IJSHandle, IAsyncDisposable

Derived: CdpElementHandle

View source

Properties

Page

protected abstract Page Page { get; }

Element’s page.

Value: Page

View source

Methods

AsLocator()

public Locator AsLocator()

Converts this IElementHandle into a Locator.

Returns: Locator — A Locator backed by this element handle.

View source

AssertConnectedElementAsync()

protected Task AssertConnectedElementAsync()

Checks whether the element is still connected to the browser.

Returns: Task — A Task representing the asynchronous operation.

Exceptions

Type	Condition
PuppeteerException	The exception if the element is not connected.

View source

AutofillAsync(AutofillData)

public abstract Task AutofillAsync(AutofillData data)

If the element is a form input, you can use AutofillAsync(AutofillData) to test if the form is compatible with the browser’s autofill implementation. Throws an error if the form cannot be autofilled.

Parameters

Name	Type	Description
`data`	AutofillData	The autofill data.

Returns: Task — A task that resolves when the autofill is complete.

Currently, Puppeteer supports auto-filling credit card information only and in Chrome in the new headless and headful modes only.

View source

BackendNodeIdAsync()

public abstract Task<int> BackendNodeIdAsync()

When connected using Chrome DevTools Protocol, it returns a DOM.BackendNodeId for the element.

Returns: Task<int> — A task that resolves to the backend node ID.

View source

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

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

Executes a function in the isolated context.

Type parameters

Name	Description
`TResult`	Return type.
`TElementHandle`	Element handle type.

Parameters

Name	Type	Description
`action`	Func<TElementHandle, Task<TResult>>	Function to execute.

Returns: Task<TResult> — Task which resolves to the result of the function.

Exceptions

Type	Condition
ArgumentNullException	Thrown if <code class=“paramref”>action</code> is `null`.

View source

BoundingBoxAsync()

public Task<BoundingBox> BoundingBoxAsync()

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

Returns: Task<BoundingBox> — The BoundingBox task.

View source

BoxModelAsync()

public Task<BoxModel> BoxModelAsync()

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

Returns: Task<BoxModel> — Task BoxModel task.

View source

ClickAsync(ClickOptions)

public Task ClickAsync(ClickOptions options = null)

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

Parameters

Name	Type	Description
`options`	ClickOptions	click options.

Returns: Task — Task which resolves when the element is successfully clicked.

Exceptions

Type	Condition
PuppeteerException	if the element is detached from DOM.

View source

ClickablePointAsync(Offset?)

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

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

Parameters

Name	Type	Description
`offset`	`Offset?`	Optional offset.

Returns: Task<BoxModelPoint> — A Task that resolves to the clickable point.

Exceptions

Type	Condition
PuppeteerException	When the node is not visible or not an HTMLElement.

View source

ContentFrameAsync()

public abstract Task<IFrame> ContentFrameAsync()

Resolves the frame associated with the element..

Returns: Task<IFrame> — Task which resolves to the frame associated with the element.

View source

DisposeAsync()

public override ValueTask DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

Returns: ValueTask — A task that represents the asynchronous dispose operation.

View source

DragAndDropAsync(IElementHandle, int)

public Task DragAndDropAsync(IElementHandle target, int delay = 0)

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

Parameters

Name	Type	Description
`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.

View source

DragAsync(IElementHandle)

public Task<DragData> DragAsync(IElementHandle target)

This method creates and captures a dragevent from the element.

Parameters

Name	Type	Description
`target`	IElementHandle	Target Element.

Returns: Task<DragData> — A Task that resolves when the message was confirmed by the browser with the drag data.

View source

DragAsync(decimal, decimal)

public Task<DragData> DragAsync(decimal x, decimal y)

This method creates and captures a dragevent from the element.

Parameters

Name	Type	Description
`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.

View source

DragEnterAsync(DragData)

public Task DragEnterAsync(DragData data)

Dispatches a dragenter event.

Parameters

Name	Type	Description
`data`	DragData	Drag data containing items and operations mask.

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

View source

DragOverAsync(DragData)

public Task DragOverAsync(DragData data)

Dispatches a dragover event.

Parameters

Name	Type	Description
`data`	DragData	Drag data containing items and operations mask.

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

View source

DropAsync(DragData)

public Task DropAsync(DragData data)

Performs a dragenter, dragover, and drop in sequence.

Parameters

Name	Type	Description
`data`	DragData	Drag data containing items and operations mask.

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

View source

DropAsync(IElementHandle)

public Task DropAsync(IElementHandle target)

Performs a dragenter, dragover, and drop in sequence.

Parameters

Name	Type	Description
`target`	IElementHandle

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

View source

FocusAsync()

public Task FocusAsync()

Calls focus <a href=“https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus">https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus</a> on the element.

Returns: Task — Task.

View source

GetPropertiesAsync()

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

Returns a Dictionary%602 with property names as keys and IJSHandle instances for the property values.

Returns: Task<Dictionary<string, IJSHandle>> — Task which resolves to a Dictionary%602.

Example

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

View source

GetPropertyAsync(string)

public override Task<IJSHandle> GetPropertyAsync(string propertyName)

Fetches a single property from the referenced object.

Parameters

Name	Type	Description
`propertyName`	string	property to get.

Returns: Task<IJSHandle> — Task of IJSHandle.

View source

HoverAsync()

public Task HoverAsync()

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

Returns: Task — Task which resolves when the element is successfully hovered.

View source

IsHiddenAsync()

public Task<bool> IsHiddenAsync()

Checks if an element is hidden using the same mechanism as WaitForSelectorOptions).

Returns: Task<bool> — Task which resolves to true if the element is hidden.

View source

IsIntersectingViewportAsync(decimal)

public Task<bool> IsIntersectingViewportAsync(decimal threshold)

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.

Parameters

Name	Type	Description
`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.

View source

IsVisibleAsync()

public Task<bool> IsVisibleAsync()

Checks if an element is visible using the same mechanism as WaitForSelectorOptions).

Returns: Task<bool> — Task which resolves to true if the element is visible.

View source

`JsonValueAsync<T>()`

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

Returns a JSON representation of the object.

Type parameters

Name	Description
`T`	A strongly typed object to parse to.

Returns: Task<T> — Task.

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.

View source

PressAsync(string, PressOptions)

public Task PressAsync(string key, PressOptions options = null)

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

Parameters

Name	Type	Description
`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.

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.

View source

QuerySelectorAllAsync(string)

public Task<IElementHandle[]> QuerySelectorAllAsync(string selector)

Runs element.querySelectorAll within the page. If no elements match the selector, the return value resolve to Empty%60%601.

Parameters

Name	Type	Description
`selector`	string	A selector to query element for.

Returns: Task<IElementHandle[]> — Task which resolves to ElementHandles pointing to the frame elements.

View source

QuerySelectorAllAsync(string, QueryOptions)

public Task<IElementHandle[]> QuerySelectorAllAsync(string selector, QueryOptions options)

Runs element.querySelectorAll within the page. If no elements match the selector, the return value resolve to Empty%60%601.

Parameters

Name	Type	Description
`selector`	string	A selector to query element for.
`options`	QueryOptions	Optional query options.

Returns: Task<IElementHandle[]> — Task which resolves to ElementHandles pointing to the frame elements.

View source

QuerySelectorAllHandleAsync(string)

public Task<IJSHandle> QuerySelectorAllHandleAsync(string selector)

A utility function to be used with Object%5b%5d).

Parameters

Name	Type	Description
`selector`	string	A selector to query element for.

Returns: Task<IJSHandle> — Task which resolves to a IJSHandle of document.querySelectorAll result.

View source

QuerySelectorAsync(string)

public Task<IElementHandle> QuerySelectorAsync(string selector)

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

Parameters

Name	Type	Description
`selector`	string	A selector to query element for.

Returns: Task<IElementHandle> — Task which resolves to IElementHandle pointing to the frame element.

View source

ScreenshotAsync(string)

public Task ScreenshotAsync(string file)

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.

Parameters

Name	Type	Description
`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.

View source

ScreenshotAsync(string, ElementScreenshotOptions)

public Task ScreenshotAsync(string file, ElementScreenshotOptions options)

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.

Parameters

Name	Type	Description
`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.

View source

ScreenshotBase64Async()

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

Returns: Task<string> — Task which resolves to a string containing the image data as base64.

View source

ScreenshotBase64Async(ElementScreenshotOptions)

public Task<string> ScreenshotBase64Async(ElementScreenshotOptions options)

Parameters

Name	Type	Description
`options`	ElementScreenshotOptions	Screenshot options.

Returns: Task<string> — Task which resolves to a string containing the image data as base64.

View source

ScreenshotDataAsync()

public Task<byte[]> ScreenshotDataAsync()

Returns: Task<byte[]> — Task which resolves to a byte[] containing the image data.

View source

ScreenshotDataAsync(ElementScreenshotOptions)

public Task<byte[]> ScreenshotDataAsync(ElementScreenshotOptions options)

Parameters

Name	Type	Description
`options`	ElementScreenshotOptions	Screenshot options.

Returns: Task<byte[]> — Task which resolves to a byte[] containing the image data.

View source

ScreenshotStreamAsync()

public Task<Stream> ScreenshotStreamAsync()

Returns: Task<Stream> — Task which resolves to a Stream containing the image data.

View source

ScreenshotStreamAsync(ElementScreenshotOptions)

public Task<Stream> ScreenshotStreamAsync(ElementScreenshotOptions options)

Parameters

Name	Type	Description
`options`	ElementScreenshotOptions	Screenshot options.

Returns: Task<Stream> — Task which resolves to a Stream containing the image data.

View source

ScrollIntoViewAsync()

public virtual Task ScrollIntoViewAsync()

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

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

View source

SelectAsync(params string[])

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

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.

Parameters

Name	Type	Description
`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.

Example

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

View source

TapAsync()

public Task TapAsync()

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

Returns: Task — Task which resolves when the element is successfully tapped.

Exceptions

Type	Condition
PuppeteerException	if the element is detached from DOM.

View source

ToString()

public override string ToString()

Returns a string that represents the current object.

Returns: string — A string that represents the current object.

View source

TouchEndAsync()

public Task TouchEndAsync()

/// Dispatches a touchendt event.

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

View source

TouchMoveAsync(ITouchHandle)

public Task TouchMoveAsync(ITouchHandle touch = null)

Dispatches a touchmove event.

Parameters

Name	Type	Description
`touch`	ITouchHandle	Optional touch handle to move. If not provided, the first active touch is moved.

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

View source

TouchStartAsync()

public Task<ITouchHandle> TouchStartAsync()

Dispatches a touchstart event.

Returns: Task<ITouchHandle> — A Task that resolves to the ITouchHandle for the started touch.

View source

TypeAsync(string, TypeOptions)

public Task TypeAsync(string text, TypeOptions options = null)

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

Parameters

Name	Type	Description
`text`	string	A text to type into a focused element.
`options`	TypeOptions	type options.

Returns: Task — Task.

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

Example

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");

View source

UploadFileAsync(bool, params string[])

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

Uploads files.

Parameters

Name	Type	Description
`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.

This method expects elementHandle to point to an input element <a href=“https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input">https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input</a>.

View source

UploadFileAsync(params string[])

public Task UploadFileAsync(params string[] filePaths)

Uploads files.

Parameters

Name	Type	Description
`filePaths`	string[]	Sets the value of the file input to these paths. Paths are resolved using GetFullPath(string).

Returns: Task — Task.

View source

WaitForSelectorAsync(string, WaitForSelectorOptions)

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

Waits for a selector to be added to the DOM.

Parameters

Name	Type	Description
`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.

View source

XPathAsync(string)

public Task<IElementHandle[]> XPathAsync(string expression)

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

Parameters

Name	Type	Description
`expression`	string	Expression to evaluate <a href=“https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate">https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate</a>.

Returns: Task<IElementHandle[]> — Task which resolves to an array of IElementHandle.

View source

Made with love by Dario Kondratiuk