***

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

All `Locator` methods available when using the **Puppeteer** driver.

Access via `runtime.page.locator(...)` 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": "locator.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?)

Clicks the located element.

```ts
await runtime.page.locator(...).click();
```

| Parameter | Type                                           | Required | Description |
| --------- | ---------------------------------------------- | -------- | ----------- |
| `options` | `Readonly&lt;PuppeteerLocatorClickOptions&gt;` | No       | —           |

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

***

### fill(value, options?)

Fills out the input identified by the locator.

<Note>
  The type of the input is determined at runtime and the appropriate fill-out
  method is chosen based on the type. contenteditable, select, textarea and
  input elements are supported.
</Note>

```ts
await runtime.page.locator(...).fill('...');
```

| Parameter | Type                                     | Required | Description |
| --------- | ---------------------------------------- | -------- | ----------- |
| `value`   | `string`                                 | Yes      | —           |
| `options` | `Readonly&lt;PuppeteerActionOptions&gt;` | No       | —           |

[Upstream docs](https://pptr.dev/api/puppeteer.locator.fill)

***

### hover(options?)

Hovers over the located element.

```ts
await runtime.page.locator(...).hover();
```

| Parameter | Type                                     | Required | Description |
| --------- | ---------------------------------------- | -------- | ----------- |
| `options` | `Readonly&lt;PuppeteerActionOptions&gt;` | No       | —           |

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

***

### scroll(options?)

Scrolls the located element.

```ts
await runtime.page.locator(...).scroll();
```

| Parameter | Type                                            | Required | Description |
| --------- | ----------------------------------------------- | -------- | ----------- |
| `options` | `Readonly&lt;PuppeteerLocatorScrollOptions&gt;` | No       | —           |

[Upstream docs](https://pptr.dev/api/puppeteer.locator.scroll)

***

## Queries

### filter(predicate)

Creates an expectation that is evaluated against located values.

<Note>
  If the expectations do not match, then the locator will retry.
  For RPC, the predicate function is serialized as a string.
</Note>

```ts
// Filter to only enabled buttons
const enabledButton = page.locator('button')
  .filter((el) => !el.disabled);
```

| Parameter   | Type                                     | Required | Description |
| ----------- | ---------------------------------------- | -------- | ----------- |
| `predicate` | `LocatorPredicate&lt;T, S&gt; \| string` | Yes      | —           |

**Returns** `RemotePuppeteerLocator&lt;S&gt;`

[Upstream docs](https://pptr.dev/api/puppeteer.locator.filter)

***

## Waiting

### wait(options?)

Waits for the locator to get the serialized value from the page.

<Note>
  Note this requires the value to be JSON-serializable.
  If a mapper was applied via map(), returns the mapped value.
</Note>

```ts
await runtime.page.locator(...).wait();
```

| Parameter | Type                                     | Required | Description |
| --------- | ---------------------------------------- | -------- | ----------- |
| `options` | `Readonly&lt;PuppeteerActionOptions&gt;` | No       | —           |

**Returns** `T`

[Upstream docs](https://pptr.dev/api/puppeteer.locator.wait)

***

### waitHandle(options?)

Waits for the locator to get a handle from the page.

```ts
await runtime.page.locator(...).waitHandle();
```

| Parameter | Type                                     | Required | Description |
| --------- | ---------------------------------------- | -------- | ----------- |
| `options` | `Readonly&lt;PuppeteerActionOptions&gt;` | No       | —           |

**Returns** `RemotePuppeteerElementHandle`

[Upstream docs](https://pptr.dev/api/puppeteer.locator.waithandle)

***

## Other

### map(mapper)

Maps the locator using the provided mapper function.

<Note>
  For RPC, the mapper function is serialized as a string.
  The result is returned when wait() is called.
</Note>

```ts
// Get the text content of an element
const text = await page.locator('h1')
  .map((el) => el.textContent)
  .wait();
```

| Parameter | Type                                  | Required | Description |
| --------- | ------------------------------------- | -------- | ----------- |
| `mapper`  | `LocatorMapper&lt;T, S&gt; \| string` | Yes      | —           |

**Returns** `RemotePuppeteerLocator&lt;S&gt;`

[Upstream docs](https://pptr.dev/api/puppeteer.locator.map)

***