***

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

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

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

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.click)

***

### hover()

Hover over the element.

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.hover)

***

### tap()

Tap the element (for touch devices).

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.tap)

***

### focus()

Focus the element.

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.focus)

***

### type(text, options?)

Type text into the element.

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.type)

***

### press(key, options?)

Press a key while focused on the element.

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.press)

***

### select(...values)

Select options in a \<select> element.

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

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.select)

***

### dragAndDrop(target, options?)

Drag and drop to another element or point.

```ts
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](https://pptr.dev/api/puppeteer.elementhandle.draganddrop)

***

## Queries

### \$(selector)

Query for a child element.

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

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle._)

***

### \$\$(selector)

Query for all matching child elements.

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

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.__)

***

### \$x(expression)

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

<Note>
  XPath queries are deprecated. Consider using CSS selectors instead.
</Note>

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

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

**Returns** `RemotePuppeteerElementHandle[]`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle._x)

***

### contentFrame()

Get the content frame for iframe elements.

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.contentframe)

***

## Content

### getProperty(propertyName)

Get a property value.

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

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

**Returns** `T`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.getproperty)

***

### jsonValue()

Get the JSON value of the element.

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

**Returns** `T`

[Upstream docs](https://pptr.dev/api/puppeteer.jshandle.jsonvalue)

***

### backendNodeId()

Get the backend node ID (Chrome DevTools Protocol).

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

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

**Returns** `number`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.backendnodeid)

***

### boundingBox()

Get the bounding box of the element.

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.boundingbox)

***

## State Checks

### isVisible()

Check if the element is visible.

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

**Returns** `boolean`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.isvisible)

***

### isHidden()

Check if the element is hidden.

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

**Returns** `boolean`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.ishidden)

***

### isIntersectingViewport(options?)

Check if the element intersects the viewport.

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

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

**Returns** `boolean`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.isintersectingviewport)

***

## Waiting

### waitForSelector(selector, options?)

Wait for a child element to appear.

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

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

**Returns** `RemotePuppeteerElementHandle \| null`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.waitforselector)

***

## Screenshots & PDF

### screenshot(options?)

Take a screenshot of the element.

<Note>
  Returns base64 string by default. If `options.encoding` is "binary", the SDK converts the base64 to a Buffer.
</Note>

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

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

**Returns** `string \| Buffer`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.screenshot)

***

## Evaluation

### evaluate(pageFunction, ...args)

Evaluate a function in the context of the element.

<Note>
  The element is passed as the first argument to the function.
</Note>

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

| Parameter      | Type                                                                             | Required | Description |
| -------------- | -------------------------------------------------------------------------------- | -------- | ----------- |
| `pageFunction` | `string \| ((element: Element, ...args: unknown[]) =&gt; T \| Promise&lt;T&gt;)` | Yes      | —           |
| `args`         | `unknown[]`                                                                      | No       | —           |

**Returns** `T`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.evaluate)

***

### \$eval(selector, pageFunction, ...args)

Evaluate a function on the first child matching the selector.

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

| Parameter      | Type                                                                             | Required | Description |
| -------------- | -------------------------------------------------------------------------------- | -------- | ----------- |
| `selector`     | `string`                                                                         | Yes      | —           |
| `pageFunction` | `string \| ((element: Element, ...args: unknown[]) =&gt; T \| Promise&lt;T&gt;)` | Yes      | —           |
| `args`         | `unknown[]`                                                                      | No       | —           |

**Returns** `T`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle._eval)

***

### \$\$eval(selector, pageFunction, ...args)

Evaluate a function on all children matching the selector.

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

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

**Returns** `T`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.__eval)

***

## Other

### uploadFile(...filePaths)

Upload files to a file input element.

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.uploadfile)

***

### scrollIntoView()

Scroll the element into view.

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.scrollintoview)

***

### autofill(data)

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

```ts
await elementHandle.autofill(/* PuppeteerAutofillData */);
```

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.autofill)

***

### boxModel()

Get the CSS box model of the element.

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.boxmodel)

***

### clickablePoint(offset?)

Get a clickable point within the element.

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

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

**Returns** `PuppeteerPoint`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.clickablepoint)

***

### frame()

Get the owning frame of this element.

```ts
elementHandle.frame();
```

**Returns** `RemotePuppeteerFrame`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.frame)

***

### drag(target)

Drag the element to the given target.

```ts
await elementHandle.drag(/* target */);
```

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

**Returns** `PuppeteerDragData \| void`

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.drag)

***

### dragEnter(data?)

Dispatch a dragenter event.

<Note>
  Deprecated: dragenter is automatically performed during dragging.
</Note>

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.dragenter)

***

### dragOver(data?)

Dispatch a dragover event.

<Note>
  Deprecated: dragover is automatically performed during dragging.
</Note>

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.dragover)

***

### drop(element)

Drop the given element onto the current one.

```ts
await elementHandle.drop(/* HandleRef */);
```

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.drop)

***

### touchStart()

Start a touch in the center of the element.

<Note>
  Scrolls element into view if needed.
</Note>

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

**Returns** `TouchHandle`
— A TouchHandle for controlling this touch point.

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.touchstart)

***

### touchMove(touch?)

Move the touch to the center of the element.

<Note>
  Scrolls element into view if needed.
</Note>

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

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.touchmove)

***

### touchEnd()

End the first active touch.

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

[Upstream docs](https://pptr.dev/api/puppeteer.elementhandle.touchend)

***

### toElement(tagName)

Convert to a typed element handle.

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

````ts
Converting to an anchor element:
```ts
const element = await page.$('.class-name-of-anchor');
const anchor = await element.toElement('a');
// 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](https://pptr.dev/api/puppeteer.elementhandle.aslocator)

***

### dispose()

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

<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://pptr.dev/api/puppeteer.jshandle.dispose)

***