page

Complete API reference for the Stagehand Page object

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];

Navigation Methods

goto()

Navigate the page to a URL and wait for a lifecycle state.

await page.goto(url: string, options?: GotoOptions): Promise<Response | null>

Returns a Response when the navigation produces a network document request, otherwise null (e.g. data: URLs or same-document navigations).

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<Response | null>

Resolves with a Response for the refreshed document when one is reported, otherwise null.

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<Response | null>

Returns a Response when the history entry triggers a network fetch; otherwise null.

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<Response | null>

Returns a Response when the navigation loads a new document from the network; otherwise null.

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.

Show properties

button · string

Mouse button to use: "left" | "right" | "middle"

Default: "left"

clickCount · number

Number of consecutive clicks.

Default: 1

returnXpath · boolean

If true, returns the XPath of the clicked element instead of void.

Default: false

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.

Show properties

delay · number

Delay between key presses in milliseconds.

withMistakes · boolean

Simulates typing with occasional mistakes and corrections.

Default: false

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

Capture the entire scrollable page instead of just the current viewport.

Default: false

clip · ScreenshotClip

Limit the capture to the provided rectangle in CSS pixels ({ x, y, width, height }). Cannot be combined with fullPage.

type · 'png' | 'jpeg'

Image format for the screenshot.

Default: "png"

quality · number

JPEG quality (0–100). Only used when type is "jpeg".

scale · 'css' | 'device'

Rendering scale. Use "css" for one pixel per CSS pixel, or "device" for the device pixel ratio.

Default: "device"

animations · 'allow' | 'disabled'

Control CSS/Web animations and transitions. "disabled" fast-forwards finite animations and pauses infinite ones before capture.

Default: "allow"

caret · hide | initial

Hide the text caret during capture ("hide") or leave it untouched ("initial").

Default: "hide"

mask · Locator[]

List of locators to cover with a colored overlay while the screenshot is taken.

maskColor · string

CSS color to use for masked overlays.

Default: #FF00FF

style · string

Additional CSS text injected into every frame just before capture. Useful for hiding or tweaking dynamic UI.

omitBackground · boolean

Make the default page background transparent (PNG only).

Default: false

timeout · number

Maximum time in milliseconds to wait for the capture before throwing.

path · string

Write the screenshot to the provided file path. The image is still returned as a buffer.

Returns: A Promise<Buffer> containing the screenshot 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

Events

on(“console”)

Listen for console output produced by the page and any adopted iframe sessions. Returns the page instance so calls can be chained.

import type { ConsoleMessage } from "@browserbasehq/stagehand";

const handleConsole = (message: ConsoleMessage) => {
  console.log(`[${message.type()}] ${message.text()}`);
  console.log("Arguments:", message.args());
  const location = message.location();
  if (location?.url) {
    console.log(`Emitted from ${location.url}:${location.lineNumber ?? 0}`);
  }
};

page.on("console", handleConsole);

ConsoleMessage exposes helpers for working with console events:

• message.type() – console API category such as log, error, or warning
• message.text() – string representation of the console arguments
• message.args() – underlying CDP RemoteObject arguments array
• message.location() – source URL, line, and column when available
• message.timestamp() – CDP timestamp for the event
• message.raw() – access to the original Runtime.consoleAPICalledEvent

once(“console”)

Register a listener that removes itself after the first console event.

page.once("console", (message) => {
  console.log("First console message:", message.text());
});

off(“console”)

Remove a previously registered listener. The reference must match the original listener passed to on().

page.off("console", handleConsole);

Code Examples

Basic Navigation

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.

ScreenshotClip

interface ScreenshotClip {
  x: number;
  y: number;
  width: number;
  height: number;
}

Represents the CSS-pixel rectangle to capture when clip is provided.

ScreenshotOptions

interface ScreenshotOptions {
  fullPage?: boolean;
  clip?: ScreenshotClip;
  type?: "png" | "jpeg";
  quality?: number;
  scale?: "css" | "device";
  animations?: "allow" | "disabled";
  caret?: "hide" | "initial";
  mask?: Locator[];
  maskColor?: string;
  style?: string;
  omitBackground?: boolean;
  timeout?: number;
  path?: string;
}

Matches Playwright’s screenshot signature with sensible defaults to control how a capture is produced.

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);
}