Playwright Element Handle | BCTRL

All Element Handle methods available when using the Playwright driver.

Access via elementHandle after launching a Playwright 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.

This method clicks the element by performing actionability checks, scrolling into view, and simulating a mouse click. Discouraged in favor of locator.click().

1 await elementHandle.click();

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

Upstream docs

dblclick(options?)

Double-click the element.

Discouraged in favor of locator.dblclick().

1 await elementHandle.dblclick();

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

Upstream docs

fill(value, options?)

Fill an input, textarea, or contenteditable element with the specified value.

This method waits for actionability checks, focuses the element, fills it, and triggers an input event. Pass empty string to clear. Discouraged in favor of locator.fill().

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

Parameter	Type	Required	Description
`value`	`string`	Yes	—
`options`	`PlaywrightFillOptions`	No	—

Upstream docs

type(text, options?)

Focus the element and type text into it character by character.

Deprecated: In most cases use locator.fill() instead. Only use this for special keyboard handling. For special keys use press().

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

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

Upstream docs

press(key, options?)

Focus the element and press a key or key combination.

Key can be a single character or a special key like “Enter”, “Control+a”, “Shift+ArrowDown”. Discouraged in favor of locator.press().

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

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

Upstream docs

hover(options?)

Hover over the element.

This method hovers over the element by performing actionability checks, scrolling into view, and simulating mouse hover. Discouraged in favor of locator.hover().

1 await elementHandle.hover();

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

Upstream docs

focus()

Focus the element.

Discouraged in favor of locator.focus().

1 await elementHandle.focus();

Upstream docs

tap(options?)

Tap the element (for touch devices).

This method taps the element by performing actionability checks, scrolling into view, centering, and dispatching touchstart/touchend events. Discouraged in favor of locator.tap().

1 await elementHandle.tap();

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

Upstream docs

check(options?)

Check a checkbox or radio element.

If the element is already checked, this method returns immediately. Discouraged in favor of locator.check().

1 await elementHandle.check();

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

Upstream docs

uncheck(options?)

Uncheck a checkbox element.

If the element is already unchecked, this method returns immediately. Discouraged in favor of locator.uncheck().

1 await elementHandle.uncheck();

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

Upstream docs

setChecked(checked, options?)

Check or uncheck a checkbox or radio element.

Discouraged in favor of locator.setChecked().

1 await elementHandle.setChecked(true);

Parameter	Type	Required	Description
`checked`	`boolean`	Yes	—
`options`	`PlaywrightCheckOptions`	No	—

Upstream docs

selectOption(values, options?)

Select one or more options in a <select> element.

Discouraged in favor of locator.selectOption().

1 await elementHandle.selectOption(/* values */);

Parameter	Type	Required	Description
`values`	`string \| string[] \| PlaywrightSelectOption \| PlaywrightSelectOption[]`	Yes	Options to select. Can be value, label, or option object.
`options`	`PlaywrightSelectOptionOptions`	No	—

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

Upstream docs

setInputFiles(files, options?)

Set the files for a file input element.

Sets the value of the file input to these file paths or files. If some paths are relative, they are resolved relative to the current working directory. Clears selected files if empty array is passed. Discouraged in favor of locator.setInputFiles().

1 await elementHandle.setInputFiles(/* files */);

Parameter	Type	Required	Description
`files`	`string \| string[] \| PlaywrightFilePayload \| PlaywrightFilePayload[]`	Yes	File paths or file payloads to upload.
`options`	`PlaywrightSetInputFilesOptions`	No	—

Upstream docs

scrollIntoViewIfNeeded(options?)

Scroll the element into view if not already visible.

If the element is detached from DOM, throws an error. Discouraged in favor of locator.scrollIntoViewIfNeeded().

1 await elementHandle.scrollIntoViewIfNeeded();

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

Upstream docs

dispatchEvent(type, eventInit?)

Dispatch a DOM event on the element.

The event is composed, cancelable and bubbles by default. Regardless of visibility, this will dispatch the event. Discouraged in favor of locator.dispatchEvent().

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

Parameter	Type	Required	Description
`type`	`string`	Yes	DOM event type, e.g., “click”.
`eventInit`	`PlaywrightEventInit`	No	Event-specific initialization properties.

Upstream docs

Queries

contentFrame()

Get the content frame for iframe elements.

1 await elementHandle.contentFrame();

Returns RemotePlaywrightFrame \| null — The frame content, or null if not an iframe.

Upstream docs

$(selector)

Query for a child element matching the selector.

Discouraged in favor of locator-based locator.locator().

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

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

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

Upstream docs

$$(selector)

Query for all child elements matching the selector.

Discouraged in favor of locator-based locator.locator().

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

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

Returns RemotePlaywrightElementHandle[] — An array of matching elements.

Upstream docs

Content

innerHTML()

Get the innerHTML of the element.

Discouraged in favor of locator.innerHTML().

1 await elementHandle.innerHTML();

Returns string

Upstream docs

innerText()

Get the innerText of the element.

Discouraged in favor of locator.innerText().

1 await elementHandle.innerText();

Returns string

Upstream docs

textContent()

Get the textContent of the element.

Discouraged in favor of locator.textContent().

1 await elementHandle.textContent();

Returns string \| null

Upstream docs

getAttribute(name)

Get an attribute value of the element.

Discouraged in favor of locator.getAttribute().

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

Parameter	Type	Required	Description
`name`	`string`	Yes	Attribute name to get.

Returns string \| null

Upstream docs

inputValue(options?)

Get the input value for input, textarea, or select elements.

Throws for non-input elements. Discouraged in favor of locator.inputValue().

1 await elementHandle.inputValue();

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

Returns string

Upstream docs

boundingBox()

Get the bounding box of the element.

Discouraged in favor of locator.boundingBox().

1 await elementHandle.boundingBox();

Returns PlaywrightBoundingBox \| null — Bounding box with x, y, width, height, or null if element is not visible.

Upstream docs

getProperty(propertyName)

Get a JSHandle for a property of this element.

Note: Returns serialized handle reference. Full JSHandle support not yet available.

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

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

Returns unknown

Upstream docs

jsonValue()

Get the JSON value of the element.

Throws if the object cannot be serialized to JSON (e.g., DOM nodes).

1 await elementHandle.jsonValue();

Returns T

Upstream docs

State Checks

isVisible()

Check if the element is visible.

Returns true if element is visible. Non-attached elements return false. Discouraged in favor of locator.isVisible().

1 await elementHandle.isVisible();

Returns boolean

Upstream docs

isHidden()

Check if the element is hidden.

Returns true if element is hidden. Non-attached elements return true. Discouraged in favor of locator.isHidden().

1 await elementHandle.isHidden();

Returns boolean

Upstream docs

isEnabled()

Check if the element is enabled.

Discouraged in favor of locator.isEnabled().

1 await elementHandle.isEnabled();

Returns boolean

Upstream docs

isDisabled()

Check if the element is disabled.

Discouraged in favor of locator.isDisabled().

1 await elementHandle.isDisabled();

Returns boolean

Upstream docs

isChecked()

Check if a checkbox or radio is checked.

Throws if element is not a checkbox or radio. Discouraged in favor of locator.isChecked().

1 await elementHandle.isChecked();

Returns boolean

Upstream docs

isEditable()

Check if the element is editable.

Discouraged in favor of locator.isEditable().

1 await elementHandle.isEditable();

Returns boolean

Upstream docs

Waiting

waitForElementState(state, options?)

Wait for the element to reach a specific state.

Discouraged in favor of web-first assertions.

1 await elementHandle.waitForElementState(/* PlaywrightElementState */);

Parameter	Type	Required	Description
`state`	`PlaywrightElementState`	Yes	State to wait for: “visible”, “hidden”, “stable”, “enabled”, or “disabled”.
`options`	`PlaywrightTimeoutOptions`	No	—

Upstream docs

waitForSelector(selector, options?)

Wait for a child element matching the selector.

Discouraged in favor of locator-based assertions.

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

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

Returns RemotePlaywrightElementHandle \| null — The matching element, or null if waiting for hidden/detached.

Upstream docs

Screenshots & PDF

screenshot(options?)

Take a screenshot of the element.

Returns base64-encoded image data. SDK converts to Buffer. Discouraged in favor of locator.screenshot().

1 await elementHandle.screenshot();

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

Returns Buffer

Upstream docs

Evaluation

evaluate(pageFunction, arg?)

Evaluate a function in the context of the element.

The element is passed as the first argument to the function. If the function returns a Promise, it will be awaited.

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

Parameter	Type	Required	Description
`pageFunction`	`string \| ((element: Element, arg: Arg) => R \| Promise<R>)`	Yes	Function or string to evaluate in the page context.
`arg`	`unknown`	No	Argument to pass to the function.

Returns R

Upstream docs

evaluateHandle(pageFunction, arg?)

Evaluate a function and return a JSHandle to the result.

The element is passed as the first argument. Note: Returns serialized handle reference. Full JSHandle support not yet available.

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

Parameter	Type	Required	Description
`pageFunction`	`string \| ((element: Element, arg: Arg) => R \| Promise<R>)`	Yes	Function or string to evaluate in the page context.
`arg`	`unknown`	No	Argument to pass to the function.

Returns unknown

Upstream docs

$eval(selector, pageFunction, arg?)

Evaluate a function on a child element matching the selector.

Throws if no element matches. Discouraged in favor of locator.evaluate().

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

Parameter	Type	Required	Description
`selector`	`string`	Yes	—
`pageFunction`	`string \| ((element: Element, arg: Arg) => R \| Promise<R>)`	Yes	—
`arg`	`unknown`	No	—

Returns R

Upstream docs

$$eval(selector, pageFunction, arg?)

Evaluate a function on all child elements matching the selector.

Discouraged in favor of locator.evaluateAll().

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

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

Returns R

Upstream docs

Other

ownerFrame()

Get the frame that owns this element.

1 await elementHandle.ownerFrame();

Returns RemotePlaywrightFrame \| null — The owner frame, or null if element is detached.

Upstream docs

asElement()

Return this handle as an ElementHandle.

Since this is already an ElementHandle, returns itself.

1 elementHandle.asElement();

Returns RemotePlaywrightElementHandle \| null

Upstream docs

dispose()

Dispose of the handle, releasing it from the browser.

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

getProperties()

Get a map of property names to JSHandles.

1 await elementHandle.getProperties();

Returns Map<string, RemotePlaywrightJSHandle>

Upstream docs