Puppeteer Element Handle | BCTRL

All Element Handle methods available when using the Puppeteer driver.

Access via elementHandle after launching a Puppeteer runtime.

How these methods work over HTTP

Every method below is a remote call. The SDK translates it into a structured step sent to a single endpoint:

POST /v1/workspaces/{workspaceId}/execute

1 {
2   "runtime": "my-browser",
3   "steps": [
4     {
5       "call": "element.goto",
6       "args": ["https://example.com"]
7     }
8   ]
9 }

The call field maps directly to the method name. args is a JSON array of the method’s arguments. You can batch multiple steps in one request.

Actions

click(options?)

Click the element.

1 await elementHandle.click();

Parameter	Type	Required	Description
`options`	`PuppeteerClickOptions`	No	—

Upstream docs

hover()

Hover over the element.

1 await elementHandle.hover();

Upstream docs

tap()

Tap the element (for touch devices).

1 await elementHandle.tap();

Upstream docs

focus()

Focus the element.

1 await elementHandle.focus();

Upstream docs

type(text, options?)

Type text into the element.

1 await elementHandle.type('...');

Parameter	Type	Required	Description
`text`	`string`	Yes	—
`options`	`PuppeteerKeyboardTypeOptions`	No	—

Upstream docs

press(key, options?)

Press a key while focused on the element.

1 await elementHandle.press('...');

Parameter	Type	Required	Description
`key`	`string`	Yes	—
`options`	`PuppeteerKeyPressOptions`	No	—

Upstream docs

select(…values)

Select options in a <select> element.

1 await elementHandle.select(/* string[] */);

Parameter	Type	Required	Description
`values`	`string[]`	Yes	—

Returns string[] — An array of selected option values.

Upstream docs

dragAndDrop(target, options?)

Drag and drop to another element or point.

1 await elementHandle.dragAndDrop(/* target */);

Parameter	Type	Required	Description
`target`	`RemotePuppeteerElementHandle \| PuppeteerPoint`	Yes	Target element or point to drop onto.
`options`	`{ delay?: number }`	No	—

Upstream docs

Queries

$(selector)

Query for a child element.

1 await elementHandle.$('...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—

Returns RemotePuppeteerElementHandle \| null — The matching element or null if not found.

Upstream docs

$$(selector)

Query for all matching child elements.

1 await elementHandle.$$('...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—

Returns RemotePuppeteerElementHandle[] — An array of matching elements.

Upstream docs

$x(expression)

Query for child elements by XPath. (Uses $$() with xpath prefix internally)

XPath queries are deprecated. Consider using CSS selectors instead.

1 await elementHandle.$x('...');

Parameter	Type	Required	Description
`expression`	`string`	Yes	—

Returns RemotePuppeteerElementHandle[]

Upstream docs

contentFrame()

Get the content frame for iframe elements.

1 await elementHandle.contentFrame();

Returns RemotePuppeteerFrame \| null — The frame or null if not an iframe.

Upstream docs

Content

getProperty(propertyName)

Get a property value.

1 await elementHandle.getProperty('...');

Parameter	Type	Required	Description
`propertyName`	`string`	Yes	—

Returns T

Upstream docs

jsonValue()

Get the JSON value of the element.

1 await elementHandle.jsonValue();

Returns T

Upstream docs

backendNodeId()

Get the backend node ID (Chrome DevTools Protocol).

This value is stable for the lifetime of the node. The SDK caches this value after the first call.

1 await elementHandle.backendNodeId();

Returns number

Upstream docs

boundingBox()

Get the bounding box of the element.

1 await elementHandle.boundingBox();

Returns PuppeteerBoundingBox \| null — The bounding box or null if the element is not visible.

Upstream docs

State Checks

isVisible()

Check if the element is visible.

1 await elementHandle.isVisible();

Returns boolean

Upstream docs

isHidden()

Check if the element is hidden.

1 await elementHandle.isHidden();

Returns boolean

Upstream docs

isIntersectingViewport(options?)

Check if the element intersects the viewport.

1 await elementHandle.isIntersectingViewport();

Parameter	Type	Required	Description
`options`	`{ threshold?: number }`	No	—

Returns boolean

Upstream docs

Waiting

waitForSelector(selector, options?)

Wait for a child element to appear.

1 await elementHandle.waitForSelector('...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—
`options`	`PuppeteerWaitForSelectorOptions`	No	—

Returns RemotePuppeteerElementHandle \| null

Upstream docs

Screenshots & PDF

screenshot(options?)

Take a screenshot of the element.

Returns base64 string by default. If options.encoding is “binary”, the SDK converts the base64 to a Buffer.

1 await elementHandle.screenshot();

Parameter	Type	Required	Description
`options`	`PuppeteerScreenshotOptions`	No	—

Returns string \| Buffer

Upstream docs

Evaluation

evaluate(pageFunction, …args)

Evaluate a function in the context of the element.

The element is passed as the first argument to the function.

1 await elementHandle.evaluate('...');

Parameter	Type	Required	Description
`pageFunction`	`string \| ((element: Element, ...args: unknown[]) => T \| Promise<T>)`	Yes	—
`args`	`unknown[]`	No	—

Returns T

Upstream docs

$eval(selector, pageFunction, …args)

Evaluate a function on the first child matching the selector.

1 await elementHandle.$eval('...', '...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—
`pageFunction`	`string \| ((element: Element, ...args: unknown[]) => T \| Promise<T>)`	Yes	—
`args`	`unknown[]`	No	—

Returns T

Upstream docs

$$eval(selector, pageFunction, …args)

Evaluate a function on all children matching the selector.

1 await elementHandle.$$eval('...', '...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—
`pageFunction`	`string \| ((elements: Element[], ...args: unknown[]) => T \| Promise<T>)`	Yes	—
`args`	`unknown[]`	No	—

Returns T

Upstream docs

Other

uploadFile(…filePaths)

Upload files to a file input element.

1 await elementHandle.uploadFile(/* string[] */);

Parameter	Type	Required	Description
`filePaths`	`string[]`	Yes	—

Upstream docs

scrollIntoView()

Scroll the element into view.

1 await elementHandle.scrollIntoView();

Upstream docs

autofill(data)

Test if the form is compatible with browser autofill. Currently supports credit card autofill in Chrome headless/headful only.

1 await elementHandle.autofill(/* PuppeteerAutofillData */);

Parameter	Type	Required	Description
`data`	`PuppeteerAutofillData`	Yes	—

Upstream docs

boxModel()

Get the CSS box model of the element.

1 await elementHandle.boxModel();

Returns PuppeteerBoxModel \| null — The box model or null if the element is not visible.

Upstream docs

clickablePoint(offset?)

Get a clickable point within the element.

1 await elementHandle.clickablePoint();

Parameter	Type	Required	Description
`offset`	`PuppeteerOffset`	No	—

Returns PuppeteerPoint

Upstream docs

frame()

Get the owning frame of this element.

1 elementHandle.frame();

Returns RemotePuppeteerFrame

Upstream docs

drag(target)

Drag the element to the given target.

1 await elementHandle.drag(/* target */);

Parameter	Type	Required	Description
`target`	`PuppeteerPoint \| RemotePuppeteerElementHandle`	Yes	Target point or element to drag to.

Returns PuppeteerDragData \| void

Upstream docs

dragEnter(data?)

Dispatch a dragenter event.

Deprecated: dragenter is automatically performed during dragging.

1 await elementHandle.dragEnter();

Parameter	Type	Required	Description
`data`	`PuppeteerDragData`	No	—

Upstream docs

dragOver(data?)

Dispatch a dragover event.

Deprecated: dragover is automatically performed during dragging.

1 await elementHandle.dragOver();

Parameter	Type	Required	Description
`data`	`PuppeteerDragData`	No	—

Upstream docs

drop(element)

Drop the given element onto the current one.

1 await elementHandle.drop(/* HandleRef */);

Parameter	Type	Required	Description
`element`	`RemotePuppeteerElementHandle`	Yes	Element to drop.

Upstream docs

touchStart()

Start a touch in the center of the element.

Scrolls element into view if needed.

1 await elementHandle.touchStart();

Returns TouchHandle — A TouchHandle for controlling this touch point.

Upstream docs

touchMove(touch?)

Move the touch to the center of the element.

Scrolls element into view if needed.

1 await elementHandle.touchMove();

Parameter	Type	Required	Description
`touch`	`{ touchId?: string }`	No	—

Upstream docs

touchEnd()

End the first active touch.

1 await elementHandle.touchEnd();

Upstream docs

toElement(tagName)

Convert to a typed element handle.

Throws if the element is not of the specified tag type. Do NOT dispose the original handle - both handles reference the same element.

1 Converting to an anchor element:
2 ```ts
3 const element = await page.$('.class-name-of-anchor');
4 const anchor = await element.toElement('a');
5 // anchor.href is now typed

| Parameter | Type | Required | Description |
|---|---|---|---|
| `tagName` | `K` | Yes | — |
**Returns** `RemotePuppeteerElementHandle`
[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.toelement)
---
### asLocator()
Create a Locator based on this ElementHandle.
<Note>
This does not refresh the handle if stale, but allows using locator conditions.
</Note>
```ts
elementHandle.asLocator();

Returns RemotePuppeteerLocator

Upstream docs

dispose()

Dispose of the handle, releasing it from the backend registry.

After disposal, any method calls will throw. The SDK sets the disposed flag before the RPC call to prevent race conditions.

1 await elementHandle.dispose();

Upstream docs