Overview
The Page class represents a single browser tab. It provides methods for navigation, element interaction, screenshots, and script evaluation.
Accessing Pages
Get pages from the context:
const page = await stagehand.context.newPage();
const activePage = stagehand.context.activePage();
Navigation Methods
goto()
Navigate to a URL.
const response = await page.goto(url, options?);
waitUntil
'load' | 'domcontentloaded' | 'networkidle'
Wait until this lifecycle eventDefault: "domcontentloaded"
Navigation timeout in millisecondsDefault: 15000
reload()
Reload the current page.
await page.reload(options?);
waitUntil
'load' | 'domcontentloaded' | 'networkidle'
goBack()
Navigate backward in history.
await page.goBack(options?);
goForward()
Navigate forward in history.
await page.goForward(options?);
url()
Get the current page URL.
const currentUrl = page.url();
title()
Get the current page title.
const pageTitle = await page.title();
Interaction Methods
click()
Click at specific coordinates.
await page.click(x, y, options?);
X coordinate in CSS pixels
Y coordinate in CSS pixels
button
'left' | 'right' | 'middle'
Mouse button to useDefault: "left"
Number of clicksDefault: 1
Return XPath of clicked element
XPath of clicked element if returnXpath is true
hover()
Hover at specific coordinates.
await page.hover(x, y, options?);
type()
Type text (focus must be on an input element).
await page.type(text, options?);
Delay between keystrokes in milliseconds
scroll()
Scroll at a specific location.
await page.scroll(x, y, deltaX, deltaY, options?);
dragAndDrop()
Drag from one point to another.
await page.dragAndDrop(fromX, fromY, toX, toY, options?);
button
'left' | 'right' | 'middle'
Number of intermediate moves
Delay between steps in milliseconds
Capture Methods
screenshot()
Capture a screenshot of the page.
const buffer = await page.screenshot(options?);
Image formatDefault: "png"
Capture full scrollable page
Clip to specific rectangle
File path to save screenshot
Make background transparent (PNG only)
Elements to mask with overlay
CSS color for mask overlayDefault: "#FF00FF"
Control animations during capture
Control text caret visibility
Evaluation Methods
evaluate()
Execute JavaScript in the page context.
const result = await page.evaluate(pageFunctionOrExpression, arg?);
pageFunctionOrExpression
string | Function
required
JavaScript expression or function to execute
Argument passed to the function
Result of evaluation (must be JSON-serializable)
addInitScript()
Add script that runs on every document load.
await page.addInitScript(script, arg?);
Locator Methods
locator()
Create a locator for element queries.
const locator = page.locator(selector);
deepLocator()
Create a locator with iframe traversal support.
const locator = page.deepLocator(selector);
Selector with optional >> iframe hops
frameLocator()
Create a frame locator for targeting iframes.
const frameLocator = page.frameLocator(selector);
Wait Methods
waitForLoadState()
Wait for a lifecycle state.
await page.waitForLoadState(state, timeoutMs?);
state
'load' | 'domcontentloaded' | 'networkidle'
required
Lifecycle state to wait for
Timeout in millisecondsDefault: 15000
waitForSelector()
Wait for an element to appear.
await page.waitForSelector(selector, options?);
CSS selector (supports >> for iframe hops)
state
'attached' | 'detached' | 'visible' | 'hidden'
Element state to wait forDefault: "visible"
Search inside shadow DOMDefault: true
waitForTimeout()
Wait for a specific duration.
await page.waitForTimeout(ms);
Other Methods
close()
Close this page (tab).
setViewportSize()
Set the viewport dimensions.
await page.setViewportSize(width, height, options?);
options.deviceScaleFactor
Device pixel ratioDefault: 1
sendCDP()
Send a raw CDP command.
const result = await page.sendCDP<T>(method, params?);
CDP method name (e.g., “Page.enable”)
Example
import { Stagehand } from "@browserbasehq/stagehand";
const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();
const page = await stagehand.context.newPage();
// Navigate
await page.goto("https://example.com", { waitUntil: "load" });
// Check URL and title
console.log(page.url());
console.log(await page.title());
// Take screenshot
const screenshot = await page.screenshot({ fullPage: true });
// Wait for element
await page.waitForSelector(".submit-button", { state: "visible" });
// Evaluate JavaScript
const result = await page.evaluate(() => {
return document.querySelectorAll("a").length;
});
await stagehand.close();