***

title: Stagehand Page
description: Complete Page method reference for the Stagehand driver.
---------------------------------------------------------------------

All `Page` methods available when using the **Stagehand** driver.

Access via `runtime.page` after launching a Stagehand 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": "page.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>

## Navigation

### goto(url, options?)

Navigate the page to a URL.

<Note>
  Options include:

  * waitUntil: 'load' | 'domcontentloaded' | 'networkidle'
  * timeoutMs: Maximum navigation time in milliseconds
</Note>

```ts
await page.goto("https://example.com");
```

| Parameter | Type                   | Required | Description         |
| --------- | ---------------------- | -------- | ------------------- |
| `url`     | `string`               | Yes      | URL to navigate to. |
| `options` | `StagehandGotoOptions` | No       | —                   |

**Returns** `RemoteStagehandResponse \| null`

[Upstream docs](https://docs.stagehand.dev/references/page#goto)

***

### reload(options?)

Reload the current page.

<Note>
  Options include:

  * waitUntil: 'load' | 'domcontentloaded' | 'networkidle'
  * timeoutMs: Maximum reload time in milliseconds
  * ignoreCache: Whether to bypass the browser cache
</Note>

```ts
await page.reload();
```

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

**Returns** `RemoteStagehandResponse \| null`

[Upstream docs](https://docs.stagehand.dev/references/page#reload)

***

### goBack(options?)

Navigate to the previous page in history.

<Note>
  Returns null if there is no previous page.
</Note>

```ts
await page.goBack();
```

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

**Returns** `RemoteStagehandResponse \| null`

[Upstream docs](https://docs.stagehand.dev/references/page#goback)

***

### goForward(options?)

Navigate to the next page in history.

<Note>
  Returns null if there is no next page.
</Note>

```ts
await page.goForward();
```

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

**Returns** `RemoteStagehandResponse \| null`

[Upstream docs](https://docs.stagehand.dev/references/page#goforward)

***

### waitForLoadState(state?, options?)

Wait for the page to reach a specific load state.

<Note>
  States:

  * 'load': Wait for the load event
  * 'domcontentloaded': Wait for DOMContentLoaded event
  * 'networkidle': Wait until no network connections for 500ms
</Note>

```ts
await page.waitForLoadState("domcontentloaded");
```

| Parameter | Type                   | Required | Description             |
| --------- | ---------------------- | -------- | ----------------------- |
| `state`   | `StagehandLoadState`   | No       | Load state to wait for. |
| `options` | `{ timeout?: number }` | No       | —                       |

[Upstream docs](https://docs.stagehand.dev/references/page#waitforloadstate)

***

## Page Info

### url()

Get the current URL of the page.

<Note>
  This is a synchronous method that returns the current URL.
</Note>

```ts
const currentUrl = page.url();
```

**Returns** `string`

[Upstream docs](https://docs.stagehand.dev/references/page#url)

***

### title()

Get the title of the page.

```ts
const title = await page.title();
```

**Returns** `string`

[Upstream docs](https://docs.stagehand.dev/references/page#title)

***

### setViewportSize(width, height, options?)

Set the viewport size of the page.

```ts
await page.setViewportSize(1280, 720);
```

| Parameter | Type                       | Required | Description                  |
| --------- | -------------------------- | -------- | ---------------------------- |
| `width`   | `number`                   | Yes      | Viewport width in pixels.    |
| `height`  | `number`                   | Yes      | Viewport height in pixels.   |
| `options` | `StagehandViewportOptions` | No       | Additional viewport options. |

[Upstream docs](https://docs.stagehand.dev/references/page#setviewportsize)

***

## Actions

### click(x, y, options?)

Click at the specified coordinates.

<Note>
  Options include:

  * button: 'left' | 'right' | 'middle' (default: 'left')
  * clickCount: Number of clicks (default: 1, use 2 for double-click)
  * returnXpath: If true, returns the XPath of the clicked element
</Note>

```ts
await page.click(100, 200);
```

| Parameter | Type                    | Required | Description            |
| --------- | ----------------------- | -------- | ---------------------- |
| `x`       | `number`                | Yes      | X coordinate to click. |
| `y`       | `number`                | Yes      | Y coordinate to click. |
| `options` | `StagehandClickOptions` | No       | —                      |

**Returns** `string \| void`

[Upstream docs](https://docs.stagehand.dev/references/page#click)

***

### hover(x, y, options?)

Hover at the specified coordinates.

<Note>
  If returnXpath is true, returns the XPath of the hovered element.
</Note>

```ts
await page.hover(300, 150);
```

| Parameter | Type                    | Required | Description                 |
| --------- | ----------------------- | -------- | --------------------------- |
| `x`       | `number`                | Yes      | X coordinate to hover over. |
| `y`       | `number`                | Yes      | Y coordinate to hover over. |
| `options` | `StagehandHoverOptions` | No       | —                           |

**Returns** `string \| void`

[Upstream docs](https://docs.stagehand.dev/references/page#hover)

***

### scroll(x, y, deltaX, deltaY)

Scroll at the specified position by the given delta.

<Note>
  Positive deltaY scrolls down, negative scrolls up.
</Note>

```ts
await page.scroll(400, 300, 0, 200); // Scroll down 200px
```

| Parameter | Type     | Required | Description                         |
| --------- | -------- | -------- | ----------------------------------- |
| `x`       | `number` | Yes      | X coordinate of scroll origin.      |
| `y`       | `number` | Yes      | Y coordinate of scroll origin.      |
| `deltaX`  | `number` | Yes      | Horizontal scroll amount in pixels. |
| `deltaY`  | `number` | Yes      | Vertical scroll amount in pixels.   |

[Upstream docs](https://docs.stagehand.dev/references/page#scroll)

***

### dragAndDrop(fromX, fromY, toX, toY, options?)

Drag from one point to another.

<Note>
  If returnXpath is true, returns \[fromXpath, toXpath] of the dragged elements.
</Note>

```ts
await page.dragAndDrop(100, 100, 300, 300);
```

| Parameter | Type                          | Required | Description            |
| --------- | ----------------------------- | -------- | ---------------------- |
| `fromX`   | `number`                      | Yes      | Starting X coordinate. |
| `fromY`   | `number`                      | Yes      | Starting Y coordinate. |
| `toX`     | `number`                      | Yes      | Ending X coordinate.   |
| `toY`     | `number`                      | Yes      | Ending Y coordinate.   |
| `options` | `StagehandDragAndDropOptions` | No       | —                      |

**Returns** `[string, string] \| void`

[Upstream docs](https://docs.stagehand.dev/references/page#draganddrop)

***

### type(text, options?)

Type text into the currently focused element.

<Note>
  The delay option adds a pause between keystrokes for realistic typing.
</Note>

```ts
await page.type("Hello, World!");
```

| Parameter | Type                   | Required | Description   |
| --------- | ---------------------- | -------- | ------------- |
| `text`    | `string`               | Yes      | Text to type. |
| `options` | `StagehandTypeOptions` | No       | —             |

[Upstream docs](https://docs.stagehand.dev/references/page#type)

***

## Queries

### locator(selector)

Create a locator for an element using a CSS or XPath selector.

<Note>
  Locators support automatic shadow DOM traversal.
</Note>

```ts
const button = page.locator("button.submit");
```

| Parameter  | Type     | Required | Description            |
| ---------- | -------- | -------- | ---------------------- |
| `selector` | `string` | Yes      | CSS or XPath selector. |

**Returns** `RemoteStagehandLocator`

[Upstream docs](https://docs.stagehand.dev/references/page#locator)

***

### deepLocator(selector)

Create a deep locator that can traverse iframes and shadow roots.

<Note>
  Deep locators use hop notation to navigate through iframes:

  * Use >>> to hop into an iframe
  * Example: "#outer-frame >>> #inner-frame >>> button"
</Note>

```ts
const nestedButton = page.deepLocator("button.nested-action");
```

| Parameter  | Type     | Required | Description                                      |
| ---------- | -------- | -------- | ------------------------------------------------ |
| `selector` | `string` | Yes      | Selector with optional hop notation for iframes. |

**Returns** `RemoteStagehandLocator`

[Upstream docs](https://docs.stagehand.dev/references/deep-locator)

***

## Waiting

### waitForSelector(selector, options?)

Wait for an element matching the selector to appear.

<Note>
  Options include:

  * state: 'visible' | 'hidden' | 'attached' | 'detached'
  * timeout: Maximum wait time in milliseconds
  * pierceShadow: Whether to pierce shadow DOM (default: true)
</Note>

```ts
await page.waitForSelector("#submit-btn");
```

| Parameter  | Type                              | Required | Description           |
| ---------- | --------------------------------- | -------- | --------------------- |
| `selector` | `string`                          | Yes      | Selector to wait for. |
| `options`  | `StagehandWaitForSelectorOptions` | No       | —                     |

[Upstream docs](https://docs.stagehand.dev/references/page#waitforselector)

***

## Screenshots & PDF

### screenshot(options?)

Capture a screenshot of the page.

<Note>
  Options include:

  * path: File path to save the screenshot
  * fullPage: Capture the full scrollable page
  * type: 'png' | 'jpeg'
  * quality: JPEG quality (0-100)
  * clip: Specific region to capture
</Note>

```ts
const buffer = await page.screenshot();
```

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

**Returns** `Buffer`

[Upstream docs](https://docs.stagehand.dev/references/page#screenshot)

***

### snapshot(options?)

Get a snapshot of the page DOM.

<Note>
  Returns a structured representation of the page content.
</Note>

```ts
const snapshot = await page.snapshot();
```

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

**Returns** `StagehandSnapshotResult`

[Upstream docs](https://docs.stagehand.dev/references/page#snapshot)

***

## Evaluation

### evaluate(pageFunction, arg?)

Execute JavaScript code within the page context.

<Note>
  The return value must be JSON-serializable.
</Note>

```ts
const title = await page.evaluate(() => document.title);
```

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

**Returns** `R`

[Upstream docs](https://docs.stagehand.dev/references/page#evaluate)

***

## Other

### addInitScript(script, arg?)

Add an initialization script that runs before page scripts.

<Note>
  The script runs on every navigation.
</Note>

```ts
await page.addInitScript(() => { window.injected = true; });
```

| Parameter | Type                                                                          | Required | Description                       |
| --------- | ----------------------------------------------------------------------------- | -------- | --------------------------------- |
| `script`  | `string \| { path?: string; content?: string } \| ((arg: Arg) =&gt; unknown)` | Yes      | The script to inject.             |
| `arg`     | `Arg`                                                                         | No       | Argument to pass to the function. |

[Upstream docs](https://docs.stagehand.dev/references/page#addinitscript)

***