Skip to main content

Page

Learn about the Stagehand Page object and browser navigation

​
Overview

The page object is the main interface for interacting with browser pages in Stagehand. It provides standard browser automation capabilities for navigation, interaction, and page inspection. Access the page object through your Stagehand instance: 
const stagehand = new Stagehand({ env: "LOCAL" });
await stagehand.init();
const page = stagehand.context.pages()[0];

​
goto()

Navigate the page to a URL and wait for a lifecycle state. 
await page.goto(url: string, options?: GotoOptions): Promise<void>
​
url
string
required
The URL to navigate to. Can be absolute or relative.
​
waitUntil
LoadState
When to consider navigation succeeded.Options:
  • "load" - Wait for the load event
  • "domcontentloaded" - Wait for DOMContentLoaded event (default)
  • "networkidle" - Wait for network to be idle
Default: "domcontentloaded"
​
timeoutMs
number
Maximum time to wait for navigation in milliseconds.Default: 15000

​
reload()

Reload the current page. 
await page.reload(options?: ReloadOptions): Promise<void>
​
waitUntil
LoadState
When to consider reload complete. See goto() for options.
​
timeoutMs
number
Maximum time to wait for reload in milliseconds.Default: 15000
​
ignoreCache
boolean
Whether to bypass the browser cache.Default: false

​
goBack()

Navigate back in browser history. 
await page.goBack(options?: NavigationOptions): Promise<void>
​
waitUntil
LoadState
When to consider navigation complete.
​
timeoutMs
number
Maximum time to wait in milliseconds.Default: 15000

​
goForward()

Navigate forward in browser history. 
await page.goForward(options?: NavigationOptions): Promise<void>
​
waitUntil
LoadState
When to consider navigation complete.
​
timeoutMs
number
Maximum time to wait in milliseconds.Default: 15000

​
Page Information

​
url()

Get the current page URL (synchronous). 
page.url(): string
Returns: The current page URL as a string.

​
title()

Get the current page title. 
await page.title(): Promise<string>
Returns: The page title as a string.

​
Interaction Methods

​
click()

Click at absolute page coordinates. 
await page.click(x: number, y: number, options?: ClickOptions): Promise<void | string>
​
x
number
required
X coordinate in CSS pixels.
​
y
number
required
Y coordinate in CSS pixels.
​
options
object
Optional click configuration.

​
type()

Type text into the page (dispatches keyboard events). 
await page.type(text: string, options?: TypeOptions): Promise<void>
​
text
string
required
The text to type.
​
options
object
Optional typing configuration.

​
locator()

Create a locator for querying elements. 
page.locator(selector: string): Locator
​
selector
string
required
CSS selector or XPath for the element.
Returns: A Locator object for interacting with the element.

​
Evaluation

​
evaluate()

Evaluate JavaScript code in the page context. 
await page.evaluate<R, Arg>(
  pageFunctionOrExpression: string | ((arg: Arg) => R | Promise<R>),
  arg?: Arg
): Promise<R>
​
pageFunctionOrExpression
string | function
required
JavaScript expression as a string or a function to execute in the page context.
​
arg
any
Optional argument to pass to the function.
Returns: The result of the evaluation (must be JSON-serializable).

​
Screenshot

​
screenshot()

Capture a screenshot of the page. 
await page.screenshot(options?: ScreenshotOptions): Promise<Buffer>
​
fullPage
boolean
Whether to capture the full scrollable page.Default: false
Returns: A Buffer containing the PNG image data.

​
Viewport

​
setViewportSize()

Set the page viewport size. 
await page.setViewportSize(
  width: number,
  height: number,
  options?: ViewportOptions
): Promise<void>
​
width
number
required
Viewport width in CSS pixels.
​
height
number
required
Viewport height in CSS pixels.
​
deviceScaleFactor
number
Device scale factor (pixel ratio).Default: 1

​
Wait Methods

​
waitForLoadState()

Wait for the page to reach a specific lifecycle state. 
await page.waitForLoadState(state: LoadState, timeoutMs?: number): Promise<void>
​
state
LoadState
required
The lifecycle state to wait for.Options: "load", "domcontentloaded", "networkidle"
​
timeoutMs
number
Maximum time to wait in milliseconds.Default: 15000

​
Code Examples

  • Basic Navigation
  • Screenshots
  • JavaScript Evaluation
  • Interaction
  • Wait for Load
  • Viewport
import { Stagehand } from "@browserbasehq/stagehand";

// Initialize with Browserbase (API key and project ID from environment variables)
// Set BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID in your environment
const stagehand = new Stagehand({ env: "BROWSERBASE" });
await stagehand.init();
const page = stagehand.context.pages()[0];

// Navigate to a URL
await page.goto("https://example.com");

// Get current URL and title
console.log("URL:", page.url());
console.log("Title:", await page.title());

// Navigate back and forward
await page.goBack();
await page.goForward();

// Reload the page
await page.reload();

​
Types

​
LoadState

type LoadState = "load" | "domcontentloaded" | "networkidle";
  • "load" - Wait for the load event (all resources loaded)
  • "domcontentloaded" - Wait for the DOMContentLoaded event (DOM is ready)
  • "networkidle" - Wait for network connections to be idle

​
AnyPage

type AnyPage = PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
Stagehand supports multiple browser automation libraries. The AnyPage type represents any compatible page object.

​
Error Handling

Page methods may throw the following errors:
  • Navigation Errors - Timeout or network issues during navigation
  • Evaluation Errors - JavaScript execution errors in evaluate()
  • Interaction Errors - Failed clicks or typing operations
  • Screenshot Errors - Issues capturing screenshots
All errors should be caught and handled appropriately: 
try {
  await page.goto("https://example.com");
} catch (error) {
  console.error("Navigation failed:", error.message);
}