***

title: Playwright Element Handle
description: Complete Element Handle method reference for the Playwright driver.
--------------------------------------------------------------------------------

All `Element Handle` methods available when using the **Playwright** driver.

Access via `elementHandle` after launching a Playwright runtime.

<Accordion title="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
  ```

  ```json
  {
    "runtime": "my-browser",
    "steps": [
      {
        "call": "element.goto",
        "args": ["https://example.com"]
      }
    ]
  }
  ```

  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.
</Accordion>

## Actions

### click(options?)

Click the element.

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

```ts
await elementHandle.click();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-click)

***

### dblclick(options?)

Double-click the element.

<Note>
  Discouraged in favor of locator.dblclick().
</Note>

```ts
await elementHandle.dblclick();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-dblclick)

***

### fill(value, options?)

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

<Note>
  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().
</Note>

```ts
await elementHandle.fill('...');
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-fill)

***

### type(text, options?)

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

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

```ts
await elementHandle.type('...');
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-type)

***

### press(key, options?)

Focus the element and press a key or key combination.

<Note>
  Key can be a single character or a special key like "Enter", "Control+a", "Shift+ArrowDown". Discouraged in favor of locator.press().
</Note>

```ts
await elementHandle.press('...');
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-press)

***

### hover(options?)

Hover over the element.

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

```ts
await elementHandle.hover();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-hover)

***

### focus()

Focus the element.

<Note>
  Discouraged in favor of locator.focus().
</Note>

```ts
await elementHandle.focus();
```

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-focus)

***

### tap(options?)

Tap the element (for touch devices).

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

```ts
await elementHandle.tap();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-tap)

***

### check(options?)

Check a checkbox or radio element.

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

```ts
await elementHandle.check();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-check)

***

### uncheck(options?)

Uncheck a checkbox element.

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

```ts
await elementHandle.uncheck();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-uncheck)

***

### setChecked(checked, options?)

Check or uncheck a checkbox or radio element.

<Note>
  Discouraged in favor of locator.setChecked().
</Note>

```ts
await elementHandle.setChecked(true);
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-set-checked)

***

### selectOption(values, options?)

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

<Note>
  Discouraged in favor of locator.selectOption().
</Note>

```ts
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](https://playwright.dev/docs/api/class-elementhandle#element-handle-select-option)

***

### setInputFiles(files, options?)

Set the files for a file input element.

<Note>
  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().
</Note>

```ts
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](https://playwright.dev/docs/api/class-elementhandle#element-handle-set-input-files)

***

### scrollIntoViewIfNeeded(options?)

Scroll the element into view if not already visible.

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

```ts
await elementHandle.scrollIntoViewIfNeeded();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-scroll-into-view-if-needed)

***

### dispatchEvent(type, eventInit?)

Dispatch a DOM event on the element.

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

```ts
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](https://playwright.dev/docs/api/class-elementhandle#element-handle-dispatch-event)

***

## Queries

### contentFrame()

Get the content frame for iframe elements.

```ts
await elementHandle.contentFrame();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-content-frame)

***

### \$(selector)

Query for a child element matching the selector.

<Note>
  Discouraged in favor of locator-based locator.locator().
</Note>

```ts
await elementHandle.$('...');
```

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

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-query-selector)

***

### \$\$(selector)

Query for all child elements matching the selector.

<Note>
  Discouraged in favor of locator-based locator.locator().
</Note>

```ts
await elementHandle.$$('...');
```

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

**Returns** `RemotePlaywrightElementHandle[]`
— An array of matching elements.

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-query-selector-all)

***

## Content

### innerHTML()

Get the innerHTML of the element.

<Note>
  Discouraged in favor of locator.innerHTML().
</Note>

```ts
await elementHandle.innerHTML();
```

**Returns** `string`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-inner-html)

***

### innerText()

Get the innerText of the element.

<Note>
  Discouraged in favor of locator.innerText().
</Note>

```ts
await elementHandle.innerText();
```

**Returns** `string`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-inner-text)

***

### textContent()

Get the textContent of the element.

<Note>
  Discouraged in favor of locator.textContent().
</Note>

```ts
await elementHandle.textContent();
```

**Returns** `string \| null`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-text-content)

***

### getAttribute(name)

Get an attribute value of the element.

<Note>
  Discouraged in favor of locator.getAttribute().
</Note>

```ts
await elementHandle.getAttribute('...');
```

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

**Returns** `string \| null`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-get-attribute)

***

### inputValue(options?)

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

<Note>
  Throws for non-input elements. Discouraged in favor of locator.inputValue().
</Note>

```ts
await elementHandle.inputValue();
```

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

**Returns** `string`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-input-value)

***

### boundingBox()

Get the bounding box of the element.

<Note>
  Discouraged in favor of locator.boundingBox().
</Note>

```ts
await elementHandle.boundingBox();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-bounding-box)

***

### getProperty(propertyName)

Get a JSHandle for a property of this element.

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

```ts
await elementHandle.getProperty('...');
```

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

**Returns** `unknown`

[Upstream docs](https://playwright.dev/docs/api/class-jshandle#js-handle-get-property)

***

### jsonValue()

Get the JSON value of the element.

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

```ts
await elementHandle.jsonValue();
```

**Returns** `T`

[Upstream docs](https://playwright.dev/docs/api/class-jshandle#js-handle-json-value)

***

## State Checks

### isVisible()

Check if the element is visible.

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

```ts
await elementHandle.isVisible();
```

**Returns** `boolean`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-is-visible)

***

### isHidden()

Check if the element is hidden.

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

```ts
await elementHandle.isHidden();
```

**Returns** `boolean`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-is-hidden)

***

### isEnabled()

Check if the element is enabled.

<Note>
  Discouraged in favor of locator.isEnabled().
</Note>

```ts
await elementHandle.isEnabled();
```

**Returns** `boolean`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-is-enabled)

***

### isDisabled()

Check if the element is disabled.

<Note>
  Discouraged in favor of locator.isDisabled().
</Note>

```ts
await elementHandle.isDisabled();
```

**Returns** `boolean`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-is-disabled)

***

### isChecked()

Check if a checkbox or radio is checked.

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

```ts
await elementHandle.isChecked();
```

**Returns** `boolean`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-is-checked)

***

### isEditable()

Check if the element is editable.

<Note>
  Discouraged in favor of locator.isEditable().
</Note>

```ts
await elementHandle.isEditable();
```

**Returns** `boolean`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-is-editable)

***

## Waiting

### waitForElementState(state, options?)

Wait for the element to reach a specific state.

<Note>
  Discouraged in favor of web-first assertions.
</Note>

```ts
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](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-element-state)

***

### waitForSelector(selector, options?)

Wait for a child element matching the selector.

<Note>
  Discouraged in favor of locator-based assertions.
</Note>

```ts
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](https://playwright.dev/docs/api/class-elementhandle#element-handle-wait-for-selector)

***

## Screenshots & PDF

### screenshot(options?)

Take a screenshot of the element.

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

```ts
await elementHandle.screenshot();
```

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

**Returns** `Buffer`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-screenshot)

***

## Evaluation

### evaluate(pageFunction, arg?)

Evaluate a function in the context of the element.

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

```ts
await elementHandle.evaluate('...');
```

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

**Returns** `R`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate)

***

### evaluateHandle(pageFunction, arg?)

Evaluate a function and return a JSHandle to the result.

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

```ts
await elementHandle.evaluateHandle('...');
```

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

**Returns** `unknown`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-evaluate-handle)

***

### \$eval(selector, pageFunction, arg?)

Evaluate a function on a child element matching the selector.

<Note>
  Throws if no element matches. Discouraged in favor of locator.evaluate().
</Note>

```ts
await elementHandle.$eval('...', '...');
```

| Parameter      | Type                                                                   | Required | Description |
| -------------- | ---------------------------------------------------------------------- | -------- | ----------- |
| `selector`     | `string`                                                               | Yes      | —           |
| `pageFunction` | `string \| ((element: Element, arg: Arg) =&gt; R \| Promise&lt;R&gt;)` | Yes      | —           |
| `arg`          | `unknown`                                                              | No       | —           |

**Returns** `R`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector)

***

### \$\$eval(selector, pageFunction, arg?)

Evaluate a function on all child elements matching the selector.

<Note>
  Discouraged in favor of locator.evaluateAll().
</Note>

```ts
await elementHandle.$$eval('...', '...');
```

| Parameter      | Type                                                                      | Required | Description |
| -------------- | ------------------------------------------------------------------------- | -------- | ----------- |
| `selector`     | `string`                                                                  | Yes      | —           |
| `pageFunction` | `string \| ((elements: Element[], arg: Arg) =&gt; R \| Promise&lt;R&gt;)` | Yes      | —           |
| `arg`          | `unknown`                                                                 | No       | —           |

**Returns** `R`

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-eval-on-selector-all)

***

## Other

### ownerFrame()

Get the frame that owns this element.

```ts
await elementHandle.ownerFrame();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-elementhandle#element-handle-owner-frame)

***

### asElement()

Return this handle as an ElementHandle.

<Note>
  Since this is already an ElementHandle, returns itself.
</Note>

```ts
elementHandle.asElement();
```

**Returns** `RemotePlaywrightElementHandle \| null`

[Upstream docs](https://playwright.dev/docs/api/class-jshandle#js-handle-as-element)

***

### dispose()

Dispose of the handle, releasing it from the browser.

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

```ts
await elementHandle.dispose();
```

[Upstream docs](https://playwright.dev/docs/api/class-jshandle#js-handle-dispose)

***

### getProperties()

Get a map of property names to JSHandles.

```ts
await elementHandle.getProperties();
```

**Returns** `Map&lt;string, RemotePlaywrightJSHandle&gt;`

[Upstream docs](https://playwright.dev/docs/api/class-jshandle#js-handle-get-properties)

***