Skip to main content
Page methods for the Stagehand driver.

​
goto

Navigate the page to a URL.
Options include:
  • waitUntil: ‘load’ | ‘domcontentloaded’ | ‘networkidle’
  • timeoutMs: Maximum navigation time in milliseconds
Upstream docs
​
url
string
required
URL to navigate to.
​
options
StagehandGotoOptions
​
result
RemoteStagehandResponse | null
Return value
await page.goto('...');

​
reload

Reload the current page.
Options include:
  • waitUntil: ‘load’ | ‘domcontentloaded’ | ‘networkidle’
  • timeoutMs: Maximum reload time in milliseconds
  • ignoreCache: Whether to bypass the browser cache
Upstream docs
​
options
StagehandReloadOptions
​
result
RemoteStagehandResponse | null
Return value
await page.reload();

​
goBack

Navigate to the previous page in history.
Returns null if there is no previous page.
Upstream docs
​
options
StagehandGotoOptions
​
result
RemoteStagehandResponse | null
Return value
await page.goBack();

​
goForward

Navigate to the next page in history.
Returns null if there is no next page.
Upstream docs
​
options
StagehandGotoOptions
​
result
RemoteStagehandResponse | null
Return value
await page.goForward();

​
waitForLoadState

Wait for the page to reach a specific load state.
States:
  • ‘load’: Wait for the load event
  • ‘domcontentloaded’: Wait for DOMContentLoaded event
  • ‘networkidle’: Wait until no network connections for 500ms
Upstream docs
​
state
StagehandLoadState
Load state to wait for.
​
options
{ timeout?: number }
await page.waitForLoadState();

​
Page Info

​
url

Get the current URL of the page.
This is a synchronous method that returns the current URL.
Upstream docs
​
result
string
Return value
await page.url();

​
title

Get the title of the page. Upstream docs
​
result
string
Return value
await page.title();

​
Actions

​
click

Click at the specified coordinates.
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
Upstream docs
​
x
number
required
X coordinate to click.
​
y
number
required
Y coordinate to click.
​
options
StagehandClickOptions
​
result
string | void
Return value
await page.click(0, 0);

​
hover

Hover at the specified coordinates.
If returnXpath is true, returns the XPath of the hovered element.
Upstream docs
​
x
number
required
X coordinate to hover over.
​
y
number
required
Y coordinate to hover over.
​
options
StagehandHoverOptions
​
result
string | void
Return value
await page.hover(0, 0);

​
scroll

Scroll at the specified position by the given delta.
Positive deltaY scrolls down, negative scrolls up.
Upstream docs
​
x
number
required
X coordinate of scroll origin.
​
y
number
required
Y coordinate of scroll origin.
​
deltaX
number
required
Horizontal scroll amount in pixels.
​
deltaY
number
required
Vertical scroll amount in pixels.
await page.scroll(0, 0, 0, 0);

​
dragAndDrop

Drag from one point to another.
If returnXpath is true, returns [fromXpath, toXpath] of the dragged elements.
Upstream docs
​
fromX
number
required
Starting X coordinate.
​
fromY
number
required
Starting Y coordinate.
​
toX
number
required
Ending X coordinate.
​
toY
number
required
Ending Y coordinate.
​
options
StagehandDragAndDropOptions
​
result
[string, string] | void
Return value
await page.dragAndDrop(0, 0, 0, 0);

​
type

Type text into the currently focused element.
The delay option adds a pause between keystrokes for realistic typing.
Upstream docs
​
text
string
required
Text to type.
​
options
StagehandTypeOptions
await page.type('...');

​
Queries

​
locator

Create a locator for an element using a CSS or XPath selector.
Locators support automatic shadow DOM traversal.
Upstream docs
​
selector
string
required
CSS or XPath selector.
​
result
RemoteStagehandLocator
Return value
await page.locator('...');

​
deepLocator

Create a deep locator that can traverse iframes and shadow roots.
Deep locators use hop notation to navigate through iframes:
  • Use >>> to hop into an iframe
  • Example: “#outer-frame >>> #inner-frame >>> button”
Upstream docs
​
selector
string
required
Selector with optional hop notation for iframes.
​
result
RemoteStagehandLocator
Return value
await page.deepLocator('...');

​
Waiting

​
waitForSelector

Wait for an element matching the selector to appear.
Options include:
  • state: ‘visible’ | ‘hidden’ | ‘attached’ | ‘detached’
  • timeout: Maximum wait time in milliseconds
  • pierceShadow: Whether to pierce shadow DOM (default: true)
Upstream docs
​
selector
string
required
Selector to wait for.
​
options
StagehandWaitForSelectorOptions
await page.waitForSelector('...');

​
Screenshots & PDF

​
screenshot

Capture a screenshot of the page.
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
Upstream docs
​
options
StagehandScreenshotOptions
​
result
Buffer
Return value
await page.screenshot();

​
snapshot

Get a snapshot of the page DOM.
Returns a structured representation of the page content.
Upstream docs
​
options
StagehandSnapshotOptions
​
result
StagehandSnapshotResult
Return value
await page.snapshot();

​
Evaluation

​
evaluate

Execute JavaScript code within the page context.
The return value must be JSON-serializable.
Upstream docs
​
pageFunction
string | ((arg: Arg) => R | Promise<R>)
required
Function or expression to evaluate in the page context.
​
arg
Arg
Argument to pass to the function.
​
result
R
Return value
await page.evaluate(/* string | ((arg: Arg) => R | Promise<R>) */);

​
Other

​
addInitScript

Add an initialization script that runs before page scripts.
The script runs on every navigation.
Upstream docs
​
script
string | { path?: string; content?: string } | ((arg: Arg) => unknown)
required
The script to inject.
​
arg
Arg
Argument to pass to the function.
await page.addInitScript(/* string | { path?: string; content?: string } | ((arg: Arg) => unknown) */);

​
setViewportSize

Set the viewport size of the page. Upstream docs
​
width
number
required
Viewport width in pixels.
​
height
number
required
Viewport height in pixels.
​
options
StagehandViewportOptions
Additional viewport options.
await page.setViewportSize(0, 0);