page - Stagehand

A Page combines deterministic browser controls with Stagehand’s natural-language act, observe, and extract methods. Navigation methods return the main-document Response, when the navigation produces one.

TypeScript
Python
Go

Quick start

const page = await browser.context.newPage();
const response = await page.goto("https://example.com");

goto()

Navigate the page to a URL.

const response = await page.goto("https://example.com");

string

The destination URL.

PageNavigationOptions

Options that configure this operation.

number

Maximum wait time in milliseconds.

LoadState

The target load state: "load", "domcontentloaded", or "networkidle". Defaults to "domcontentloaded".

Promise<Response | null>

The final main-document response, or null when no network response was produced.

reload()

Reload the current page.

await page.reload();

PageReloadOptions

Options that configure this operation.

boolean

Whether to bypass the browser cache.

number

Maximum wait time in milliseconds.

LoadState

The target load state: "load", "domcontentloaded", or "networkidle". Defaults to "domcontentloaded".

Promise<Response | null>

The final main-document response, or null when no network response was produced.

goBack()

Navigate backward in the page history.

await page.goBack();

PageNavigationOptions

Options that configure this operation.

number

Maximum wait time in milliseconds.

LoadState

The target load state: "load", "domcontentloaded", or "networkidle". Defaults to "domcontentloaded".

Promise<Response | null>

The final main-document response, or null when no history navigation occurred or no network response was produced.

goForward()

Navigate forward in the page history.

await page.goForward();

PageNavigationOptions

Options that configure this operation.

number

Maximum wait time in milliseconds.

LoadState

The target load state: "load", "domcontentloaded", or "networkidle". Defaults to "domcontentloaded".

Promise<Response | null>

The final main-document response, or null when no history navigation occurred or no network response was produced.

click()

Click at page coordinates.

await page.click(240, 320);

number

The horizontal page coordinate.

number

The vertical page coordinate.

PageClickOptions

Options that configure this operation.

MouseButton

The mouse button to use: "left", "middle", or "right".

number

The number of clicks to dispatch.

Promise<void>

Resolves after the operation completes.

hover()

Move the pointer to page coordinates.

await page.hover(240, 320);

number

The horizontal page coordinate.

number

The vertical page coordinate.

Promise<void>

Resolves after the operation completes.

scroll()

Scroll from page coordinates by the supplied deltas.

await page.scroll(240, 320, 0, 600);

number

The horizontal page coordinate.

number

The vertical page coordinate.

number

Horizontal scroll distance.

number

Vertical scroll distance.

Promise<void>

Resolves after the operation completes.

dragAndDrop()

Drag from one page coordinate to another.

await page.dragAndDrop(100, 100, 400, 400);

number

The drag origin’s horizontal coordinate.

number

The drag origin’s vertical coordinate.

number

The drop target’s horizontal coordinate.

number

The drop target’s vertical coordinate.

PageDragAndDropOptions

Options that configure this operation.

MouseButton

The mouse button to use: "left", "middle", or "right".

number

The input delay in milliseconds.

number

The number of intermediate pointer moves.

PageDragAndDropRoutePoint[]

An ordered mouse route to follow instead of generating linear intermediate moves. The explicit toX and toY coordinates remain the final point.

number

A route point’s horizontal coordinate.

number

A route point’s vertical coordinate.

Promise<void>

Resolves after the operation completes.

type()

Type text at the current input target.

await page.type("Browserbase");

string

The text to type.

PageTypeOptions

Options that configure this operation.

number

The input delay in milliseconds.

boolean

Whether to simulate occasional typing mistakes.

Promise<void>

Resolves after the operation completes.

keyPress()

Send a keyboard key press to the page.

await page.keyPress("Enter");

string

The keyboard key to send.

PageKeyPressOptions

Options that configure this operation.

number

The input delay in milliseconds.

Promise<void>

Resolves after the operation completes.

evaluate()

Evaluate JavaScript in the page and return its result.

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

string | ((arg: Arg) => R | Promise<R>)

JavaScript source or a function to evaluate.

Arg

An optional argument passed to the function.

Promise<R>

The operation result.

on()

Subscribe to console messages from this page and its page-owned sessions. Stagehand delivers each message using the underlying "Runtime.consoleAPICalled" event envelope.

const subscription = await page.on("console", (event) => {
  console.log(event.method, event.params);
});

await page.evaluate(() => console.log("ready"));
await subscription.unsubscribe();

PageEventName

The console event name. Currently, the only supported value is "console".

PageEventListener

A callback that receives the event method, raw parameters, session ID, target ID, and page ID. Async callbacks may overlap and are not awaited by later page calls.

Promise<CDPSubscription>

A subscription handle whose unsubscribe() method stops delivery.

CDPSubscription

unsubscribe(): Promise<void> removes the listener locally and from the Stagehand runtime. Repeated calls share the completed cleanup. A failed runtime request can be retried by calling unsubscribe() again.

addInitScript()

Run a script before other scripts whenever the page navigates.

await page.addInitScript(() => {
  window.localStorage.clear();
});

InitScriptSource<Arg>

A function, JavaScript source string, or object with exactly one of path and content.

Arg

An optional JSON-serializable argument. Valid only when script is a function.

Promise<void>

Resolves after the operation completes.

setExtraHTTPHeaders()

Set additional HTTP headers for this page.

await page.setExtraHTTPHeaders({ "x-test": "true" });

Record<string, string>

HTTP header names and values.

Promise<void>

Resolves after the operation completes.

setViewportSize()

Set the page viewport dimensions.

await page.setViewportSize(1440, 900);

number

Viewport width in CSS pixels.

number

Viewport height in CSS pixels.

PageSetViewportSizeOptions

Options that configure this operation.

number

The device scale factor.

Promise<void>

Resolves after the operation completes.

waitForLoadState()

Wait until the page reaches a load state.

await page.waitForLoadState("networkidle", 10_000);

LoadState

The state to wait for: "load", "domcontentloaded", or "networkidle".

number

Maximum wait time in milliseconds.

Promise<void>

Resolves after the operation completes.

waitForTimeout()

Wait for a fixed number of milliseconds.

await page.waitForTimeout(500);

number

The number of milliseconds to wait.

Promise<void>

Resolves after the operation completes.

waitForSelector()

Wait for a selector to reach the requested state.

const matched = await page.waitForSelector("main");

string

The selector to target.

PageWaitForSelectorOptions

Options that configure this operation.

boolean

Whether to traverse shadow roots. Closed roots require a navigated page; see the locator reference.

PageWaitForSelectorOptions['state']

The state to wait for: "attached", "detached", "visible", or "hidden".

number

The operation timeout in milliseconds.

Promise<boolean>

The operation result.

screenshot()

Capture a screenshot of the page.

const image = await page.screenshot({ fullPage: true });

ScreenshotOptions

Options that configure this operation.

ScreenshotOptions['animations']

How to handle active animations: "disabled" or "allow".

ScreenshotOptions['caret']

How to render the text caret: "hide" or "initial".

PageScreenshotClip

The screenshot crop rectangle.

number

The positive height in CSS pixels.

number

The positive width in CSS pixels.

number

The horizontal coordinate.

number

The vertical coordinate.

boolean

Whether to capture the full scrollable page. Cannot be combined with clip.

Locator[]

Page-created locators for elements to obscure. Every locator must belong to this page.

string

The CSS mask color.

boolean

Whether to use a transparent background.

string

A file path where the image is also written.

number

JPEG quality as an integer from 0 to 100. Valid only when type is "jpeg".

ScreenshotOptions['scale']

Whether to use "css" or "device" pixel scale.

string

CSS applied while taking the screenshot.

number

The non-negative operation timeout in milliseconds.

ScreenshotOptions['type']

The image format: "png" or "jpeg".

Promise<Uint8Array>

The screenshot image bytes.

snapshot()

Capture the page’s accessibility-oriented DOM snapshot.

const snapshot = await page.snapshot();

PageSnapshotOptions

Options that configure this operation.

boolean

Whether to include iframe content.

Promise<SnapshotResult>

The operation result.

string

The formatted page tree.

object

The snapshot URL lookup.

object

The snapshot XPath lookup.

tools()

Return the WebMCP tools registered on the page.

const tools = await page.tools();

const searchTool = tools.find((tool) => tool.name === "search");
if (!searchTool) throw new Error("Search tool is unavailable");

console.log(searchTool.inputSchema);

const invocation = await searchTool.invoke({
  input: { query: "Stagehand" },
});
const result = await invocation.result();
console.log(result.status, result.output);

WebMCPToolsOptions

Options that configure tool discovery.

number

Maximum time in milliseconds to wait for registered tools.

Promise<WebMCPTool[]>

The callable WebMCP tools registered on the page. See the WebMCP reference.

url()

Return the page’s current URL.

const url = await page.url();

Promise<string>

The operation result.

title()

Return the page’s current document title.

const title = await page.title();

Promise<string>

The operation result.

close()

Close the page.

await page.close();

Promise<void>

Resolves after the operation completes.

locator()

Create a locator for a CSS selector on this page.

const locator = page.locator("button[type=submit]");

string

The selector to target.

Locator

The operation result.

Quick start

page = await browser.context.new_page()
response = await page.goto("https://example.com")

goto()

Navigate the page to a URL.

response = await page.goto("https://example.com")

str

The destination URL.

LoadState | Literal['load', 'domcontentloaded', 'networkidle']

The load state to wait for. Defaults to "domcontentloaded".

int | None

Maximum wait time in milliseconds.

Response | None

The final main-document response, or None when no network response was produced.

reload()

Reload the current page.

await page.reload()

LoadState | Literal['load', 'domcontentloaded', 'networkidle']

The load state to wait for. Defaults to "domcontentloaded".

int | None

Maximum wait time in milliseconds.

bool | None

Whether to bypass the browser cache.

Response | None

The final main-document response, or None when no network response was produced.

go_back()

Navigate backward in the page history.

await page.go_back()

LoadState | Literal['load', 'domcontentloaded', 'networkidle']

The load state to wait for. Defaults to "domcontentloaded".

int | None

Maximum wait time in milliseconds.

Response | None

The final main-document response, or None when no history navigation occurred or no network response was produced.

go_forward()

Navigate forward in the page history.

await page.go_forward()

LoadState | Literal['load', 'domcontentloaded', 'networkidle']

The load state to wait for. Defaults to "domcontentloaded".

int | None

Maximum wait time in milliseconds.

Response | None

The final main-document response, or None when no history navigation occurred or no network response was produced.

click()

Click at page coordinates.

await page.click(240, 320)

float

The horizontal page coordinate.

float

The vertical page coordinate.

MouseButton | Literal['left', 'right', 'middle']

The mouse button to use.

int | None

The number of clicks to dispatch.

None

Resolves after the operation completes.

hover()

Move the pointer to page coordinates.

await page.hover(240, 320)

float

The horizontal page coordinate.

float

The vertical page coordinate.

None

Resolves after the operation completes.

scroll()

Scroll from page coordinates by the supplied deltas.

await page.scroll(240, 320, 0, 600)

float

The horizontal page coordinate.

float

The vertical page coordinate.

float

Horizontal scroll distance.

float

Vertical scroll distance.

None

Resolves after the operation completes.

drag_and_drop()

Drag from one page coordinate to another.

await page.drag_and_drop(100, 100, 400, 400)

float

The drag origin’s horizontal coordinate.

float

The drag origin’s vertical coordinate.

float

The drop target’s horizontal coordinate.

float

The drop target’s vertical coordinate.

MouseButton | Literal['left', 'right', 'middle']

The mouse button to use.

int | None

The number of intermediate pointer moves.

float | None

An optional input delay in milliseconds.

Sequence[PageDragAndDropRoutePoint | Mapping[str, float]] | None

An ordered mouse route to follow instead of generating linear intermediate moves. The explicit to_x and to_y coordinates remain the final point.

float

A route point’s horizontal coordinate.

float

A route point’s vertical coordinate.

None

Resolves after the operation completes.

type()

Type text at the current input target.

await page.type("Browserbase")

str

The text to type.

float | None

An optional input delay in milliseconds.

bool | None

Whether to simulate occasional typing mistakes.

None

Resolves after the operation completes.

key_press()

Send a keyboard key press to the page.

await page.key_press("Enter")

str

The keyboard key to send.

float | None

An optional input delay in milliseconds.

None

Resolves after the operation completes.

evaluate()

Evaluate JavaScript in the page and return its result.

title = await page.evaluate("document.title", result_type=str)

str

JavaScript source or a function to evaluate.

type[EvaluateResult] | None

An optional Python type used to validate the result.

JsonValue | EvaluateResult

The operation result.

on()

Subscribe to console messages from this page and its page-owned sessions. Stagehand delivers each message using the underlying "Runtime.consoleAPICalled" event envelope.

async def handle_console(event: PageCDPEvent) -> None:
    print(event.method, event.params)

subscription = await page.on("console", handle_console)
await page.evaluate('console.log("ready")')
await subscription.unsubscribe()

PageEventName

The console event name. Currently, the only supported value is "console".

PageEventListener

A sync or async callback that receives the event method, raw parameters, session ID, target ID, and page ID. Async callbacks may overlap and are not awaited by later page calls.

CDPSubscription

A subscription handle whose unsubscribe() method stops delivery.

CDPSubscription

await subscription.unsubscribe() removes the listener locally and from the Stagehand runtime. Repeated calls await the same successful cleanup. Failed cleanup can be retried. If the caller is cancelled while awaiting cleanup, the shared cleanup task continues in the background.

add_init_script()

Run a script before other scripts whenever the page navigates.

await page.add_init_script("window.localStorage.clear()")

str | Path

JavaScript source or a path to a JavaScript file on the SDK caller’s machine.

None

Resolves after the operation completes.

set_extra_http_headers()

Set additional HTTP headers for this page.

await page.set_extra_http_headers({"x-test": "true"})

Mapping[str, str]

HTTP header names and values.

None

Resolves after the operation completes.

set_viewport_size()

Set the page viewport dimensions.

await page.set_viewport_size(1440, 900)

int

Viewport width in CSS pixels.

int

Viewport height in CSS pixels.

float | None

The device scale factor.

None

Resolves after the operation completes.

wait_for_load_state()

Wait until the page reaches a load state.

await page.wait_for_load_state("networkidle", timeout=10_000)

LoadState | Literal['load', 'domcontentloaded', 'networkidle']

The state to wait for: "load", "domcontentloaded", or "networkidle".

int | None

Maximum wait time in milliseconds.

None

Resolves after the operation completes.

wait_for_timeout()

Wait for a fixed number of milliseconds.

await page.wait_for_timeout(500)

int

The number of milliseconds to wait.

None

Resolves after the operation completes.

wait_for_selector()

Wait for a selector to reach the requested state.

matched = await page.wait_for_selector("main", state="visible")

str

The selector to target.

State | Literal['attached', 'detached', 'visible', 'hidden']

The state to wait for: "attached", "detached", "visible", or "hidden".

int | None

Maximum wait time in milliseconds.

bool | None

Whether to traverse shadow roots. Closed roots require a navigated page; see the locator reference.

bool

The operation result.

screenshot()

Capture a screenshot of the page.

image = await page.screenshot(full_page=True)

Animations | Literal['disabled', 'allow']

How to handle CSS animations: "disabled" or "allow".

Caret | Literal['hide', 'initial']

How to render the text caret: "hide" or "initial".

PageScreenshotClip | None

The region to capture.

float

The positive height in CSS pixels.

float

The positive width in CSS pixels.

float

The horizontal coordinate.

float

The vertical coordinate.

bool | None

Whether to capture the full scrollable page. Cannot be combined with clip.

str | Path | None

A path where the image is also written.

Sequence[Locator] | None

Page-created locators for elements to obscure. Every locator must belong to this page.

str | None

The CSS color used for masks.

bool | None

Whether to use a transparent background.

int | None

JPEG quality as an integer from 0 to 100. Valid only when type is "jpeg".

Scale | Literal['css', 'device']

Whether to use "css" or "device" pixel scale.

str | None

CSS applied while taking the screenshot.

float | None

Maximum non-negative wait time in milliseconds.

ScreenshotType | Literal['png', 'jpeg']

The image format: "png" or "jpeg".

bytes

The operation result.

snapshot()

Capture the page’s accessibility-oriented DOM snapshot.

snapshot = await page.snapshot()

bool | None

Whether to include iframe content.

SnapshotResult

The operation result.

str

The formatted page tree.

dict[str, object]

The snapshot URL lookup.

dict[str, object]

The snapshot XPath lookup.

tools()

Return the WebMCP tools registered on the page.

tools = await page.tools()

search_tool = next((tool for tool in tools if tool.name == "search"), None)
if search_tool is None:
    raise RuntimeError("Search tool is unavailable")

print(search_tool.input_schema)

invocation = await search_tool.invoke(input={"query": "Stagehand"})
result = await invocation.result()
print(result.status, result.output)

float | None

Maximum time in milliseconds to wait for registered tools.

list[WebMCPTool]

The callable WebMCP tools registered on the page. See the WebMCP reference.

url()

Return the page’s current URL.

url = await page.url()

str

The operation result.

title()

Return the page’s current document title.

title = await page.title()

str

The operation result.

close()

Close the page.

await page.close()

None

Resolves after the operation completes.

locator()

Create a locator for a CSS selector on this page.

locator = page.locator("button[type=submit]")

str

The selector to target.

Locator

The operation result.

Quick start

browserContext, err := browser.Context()
if err != nil {
    return err
}
page, err := browserContext.NewPage(ctx)
if err != nil {
    return err
}
if _, err := page.Goto(ctx, "https://example.com", nil); err != nil {
    return err
}

Every method that talks to the browser takes a context.Context first and returns an error last; the local Locator() accessor takes neither. Options are passed as pointer structs; pass nil for defaults.

Goto()

Navigate the page to a URL.

if _, err := page.Goto(ctx, "https://example.com", nil); err != nil {
    return err
}

string

The destination URL.

*PageNavigationOptions

Options that configure this operation. Pass nil for defaults.

*int

Maximum wait time in milliseconds.

*LoadState

The target load state: LoadStateLoad, LoadStateDOMContentLoaded, or LoadStateNetworkIdle. Defaults to LoadStateDOMContentLoaded.

(*Response, error)

The final main-document response, or nil when no network response was produced.

Reload()

Reload the current page.

if _, err := page.Reload(ctx, nil); err != nil {
    return err
}

*PageReloadOptions

Options that configure this operation. Pass nil for defaults.

*bool

Whether to bypass the browser cache.

*int

Maximum wait time in milliseconds.

*LoadState

The target load state: LoadStateLoad, LoadStateDOMContentLoaded, or LoadStateNetworkIdle. Defaults to LoadStateDOMContentLoaded.

(*Response, error)

The final main-document response, or nil when no network response was produced.

GoBack()

Navigate backward in the page history.

if _, err := page.GoBack(ctx, nil); err != nil {
    return err
}

*PageNavigationOptions

Options that configure this operation. Pass nil for defaults.

*int

Maximum wait time in milliseconds.

*LoadState

The target load state: LoadStateLoad, LoadStateDOMContentLoaded, or LoadStateNetworkIdle. Defaults to LoadStateDOMContentLoaded.

(*Response, error)

The final main-document response, or nil when no history navigation occurred or no network response was produced.

GoForward()

Navigate forward in the page history.

if _, err := page.GoForward(ctx, nil); err != nil {
    return err
}

*PageNavigationOptions

Options that configure this operation. Pass nil for defaults.

*int

Maximum wait time in milliseconds.

*LoadState

The target load state: LoadStateLoad, LoadStateDOMContentLoaded, or LoadStateNetworkIdle. Defaults to LoadStateDOMContentLoaded.

(*Response, error)

The final main-document response, or nil when no history navigation occurred or no network response was produced.

Click()

Click at page coordinates.

if err := page.Click(ctx, 240, 320, nil); err != nil {
    return err
}

float64

The horizontal page coordinate.

float64

The vertical page coordinate.

*PageClickOptions

Options that configure this operation. Pass nil for defaults.

*MouseButton

The mouse button to use: MouseButtonLeft, MouseButtonMiddle, or MouseButtonRight.

*int

The number of clicks to dispatch.

error

Returns nil after the operation completes.

Hover()

Move the pointer to page coordinates.

if err := page.Hover(ctx, 240, 320); err != nil {
    return err
}

float64

The horizontal page coordinate.

float64

The vertical page coordinate.

error

Returns nil after the operation completes.

Scroll()

Scroll from page coordinates by the supplied deltas.

if err := page.Scroll(ctx, 240, 320, 0, 600); err != nil {
    return err
}

float64

The horizontal page coordinate.

float64

The vertical page coordinate.

float64

Horizontal scroll distance.

float64

Vertical scroll distance.

error

Returns nil after the operation completes.

DragAndDrop()

Drag from one page coordinate to another.

if err := page.DragAndDrop(ctx, 100, 100, 400, 400, nil); err != nil {
    return err
}

float64

The drag origin’s horizontal coordinate.

float64

The drag origin’s vertical coordinate.

float64

The drop target’s horizontal coordinate.

float64

The drop target’s vertical coordinate.

*PageDragAndDropOptions

Options that configure this operation. Pass nil for defaults.

*MouseButton

The mouse button to use: MouseButtonLeft, MouseButtonMiddle, or MouseButtonRight.

*float64

The input delay in milliseconds.

*int

The number of intermediate pointer moves.

[]PageDragAndDropRoutePoint

An ordered mouse route to follow instead of generating linear intermediate moves. The explicit toX and toY coordinates remain the final point.

float64

A route point’s horizontal coordinate.

float64

A route point’s vertical coordinate.

error

Returns nil after the operation completes.

Type()

Type text at the current input target.

if err := page.Type(ctx, "Browserbase", nil); err != nil {
    return err
}

string

The text to type.

*PageTypeOptions

Options that configure this operation. Pass nil for defaults.

*float64

The input delay in milliseconds.

*bool

Whether to simulate occasional typing mistakes.

error

Returns nil after the operation completes.

KeyPress()

Send a keyboard key press to the page.

if err := page.KeyPress(ctx, "Enter", nil); err != nil {
    return err
}

string

The keyboard key to send.

*PageKeyPressOptions

Options that configure this operation. Pass nil for defaults.

*float64

The input delay in milliseconds.

error

Returns nil after the operation completes.

Evaluate()

Evaluate JavaScript in the page and return its result. Evaluate returns the raw JSON value; use the package-level generic EvaluateAs to decode the result into a Go type.

title, err := stagehand.EvaluateAs[string](ctx, page, "document.title")
if err != nil {
    return err
}
fmt.Println(title)

string

JavaScript source to evaluate.

(json.RawMessage, error)

The operation result as raw JSON. EvaluateAs[T] decodes it into T instead.

On()

Subscribe to console messages from this page and its page-owned sessions. Stagehand delivers each message using the underlying "Runtime.consoleAPICalled" event envelope.

subscription, err := page.On(ctx, stagehand.PageEventNameConsole, func(event stagehand.PageCDPEvent) {
    fmt.Println(event.Method, event.Params)
})
if err != nil {
    return err
}

if _, err := page.Evaluate(ctx, `console.log("ready")`); err != nil {
    return err
}
if err := subscription.Close(ctx); err != nil {
    return err
}

PageEventName

The console event name. Currently, the only supported value is PageEventNameConsole.

func(PageCDPEvent)

A callback that receives the event method, raw parameters, session ID, target ID, and page ID. Listeners are not awaited by later page calls.

(*CDPSubscription, error)

A subscription handle whose Close() method stops delivery.

CDPSubscription

Close(ctx context.Context) error removes the listener locally and from the Stagehand runtime. Repeated calls after successful cleanup return nil. Concurrent calls share the active cleanup; a failed attempt can be retried.

AddInitScript()

Run a script before other scripts whenever the page navigates.

if err := page.AddInitScript(ctx, "window.localStorage.clear()"); err != nil {
    return err
}

string

JavaScript source. Go functions and file paths are not interpreted.

error

Returns nil after the operation completes.

SetExtraHTTPHeaders()

Set additional HTTP headers for this page.

headers := stagehand.PageSetExtraHTTPHeadersParamsHeaders{"x-test": "true"}
if err := page.SetExtraHTTPHeaders(ctx, headers); err != nil {
    return err
}

PageSetExtraHTTPHeadersParamsHeaders

HTTP header names and values, as a map[string]string.

error

Returns nil after the operation completes.

SetViewportSize()

Set the page viewport dimensions.

if err := page.SetViewportSize(ctx, 1440, 900, nil); err != nil {
    return err
}

int

Viewport width in CSS pixels.

int

Viewport height in CSS pixels.

*PageSetViewportSizeOptions

Options that configure this operation. Pass nil for defaults.

*float64

The device scale factor.

error

Returns nil after the operation completes.

WaitForLoadState()

Wait until the page reaches a load state.

timeout := 10_000
if err := page.WaitForLoadState(ctx, stagehand.LoadStateNetworkIdle, &timeout); err != nil {
    return err
}

LoadState

The state to wait for: LoadStateLoad, LoadStateDOMContentLoaded, or LoadStateNetworkIdle.

*int

Maximum wait time in milliseconds. Pass nil for the default.

error

Returns nil after the operation completes.

WaitForTimeout()

Wait for a fixed number of milliseconds.

if err := page.WaitForTimeout(ctx, 500); err != nil {
    return err
}

int

The number of milliseconds to wait.

error

Returns nil after the operation completes.

WaitForSelector()

Wait for a selector to reach the requested state.

matched, err := page.WaitForSelector(ctx, "main", nil)
if err != nil {
    return err
}
fmt.Println(matched)

string

The selector to target.

*PageWaitForSelectorOptions

Options that configure this operation. Pass nil for defaults.

*bool

Whether to traverse shadow roots. Closed roots require a navigated page; see the locator reference.

*PageWaitForSelectorOptionsState

The state to wait for: PageWaitForSelectorOptionsStateAttached, PageWaitForSelectorOptionsStateDetached, PageWaitForSelectorOptionsStateVisible, or PageWaitForSelectorOptionsStateHidden.

*int

The operation timeout in milliseconds.

(bool, error)

The operation result.

Screenshot()

Capture a screenshot of the page. There is no path option in Go; write the returned bytes yourself, for example with os.WriteFile.

fullPage := true
image, err := page.Screenshot(ctx, &stagehand.ScreenshotOptions{FullPage: &fullPage})
if err != nil {
    return err
}
if err := os.WriteFile("screenshot.png", image, 0o644); err != nil {
    return err
}

*ScreenshotOptions

Options that configure this operation. Pass nil for defaults.

*PageScreenshotOptionsAnimations

How to handle active animations: PageScreenshotOptionsAnimationsDisabled or PageScreenshotOptionsAnimationsAllow.

*PageScreenshotOptionsCaret

How to render the text caret: PageScreenshotOptionsCaretHide or PageScreenshotOptionsCaretInitial.

*PageScreenshotClip

The screenshot crop rectangle.

float64

The positive height in CSS pixels.

float64

The positive width in CSS pixels.

float64

The horizontal coordinate.

float64

The vertical coordinate.

*bool

Whether to capture the full scrollable page. Cannot be combined with options.Clip.

[]*PageLocator

Page-created locators for elements to obscure in the screenshot. Create each with page.Locator("..."); every mask locator must belong to the page being captured.

*string

The CSS mask color.

*bool

Whether to use a transparent background.

*int

JPEG quality as an integer from 0 to 100. Valid only when options.Type is PageScreenshotOptionsTypeJPEG.

*PageScreenshotOptionsScale

Whether to use PageScreenshotOptionsScaleCSS or PageScreenshotOptionsScaleDevice.

*string

CSS applied while taking the screenshot.

*float64

The non-negative operation timeout in milliseconds.

*PageScreenshotOptionsType

The image format: PageScreenshotOptionsTypePNG or PageScreenshotOptionsTypeJPEG.

([]byte, error)

The screenshot image bytes.

Snapshot()

Capture the page’s accessibility-oriented DOM snapshot.

snapshot, err := page.Snapshot(ctx, nil)
if err != nil {
    return err
}
fmt.Println(snapshot.FormattedTree)

*PageSnapshotOptions

Options that configure this operation. Pass nil for defaults.

*bool

Whether to include iframe content.

(SnapshotResult, error)

The operation result.

string

The formatted page tree.

SnapshotResultURLMap

The snapshot URL lookup.

SnapshotResultXPathMap

The snapshot XPath lookup.

Tools()

Return the WebMCP tools registered on the page.

tools, err := page.Tools(ctx, nil)
if err != nil {
    return err
}

var searchTool *stagehand.WebMCPTool
for _, tool := range tools {
    if tool.Descriptor().Name == "search" {
        searchTool = tool
        break
    }
}
if searchTool == nil {
    return errors.New("search tool is unavailable")
}

fmt.Println(searchTool.Descriptor().InputSchema)

invocation, err := searchTool.Invoke(ctx, stagehand.WebMCPInput{"query": "Stagehand"})
if err != nil {
    return err
}
result, err := invocation.Result(ctx, nil)
if err != nil {
    return err
}
fmt.Println(result.Status, result.Output)

*WebMCPToolsOptions

Options that configure tool discovery. Pass nil for defaults.

float64

Maximum time in milliseconds to wait for registered tools.

([]*WebMCPTool, error)

The callable WebMCP tools registered on the page. See the WebMCP reference.

URL()

Return the page’s current URL.

url, err := page.URL(ctx)
if err != nil {
    return err
}
fmt.Println(url)

(string, error)

The operation result.

Title()

Return the page’s current document title.

title, err := page.Title(ctx)
if err != nil {
    return err
}
fmt.Println(title)

(string, error)

The operation result.

Close()

Close the page.

if err := page.Close(ctx); err != nil {
    return err
}

error

Returns nil after the operation completes.

Locator()

Create a locator for a CSS selector on this page.

locator := page.Locator("button[type=submit]")
if err := locator.Click(ctx, nil); err != nil {
    return err
}

string

The selector to target.

*PageLocator

The operation result.

​Quick start

​goto()

​reload()

​goBack()

​goForward()

​click()

​hover()

​scroll()

​dragAndDrop()

​type()

​keyPress()

​evaluate()

​on()

​CDPSubscription

​addInitScript()

​setExtraHTTPHeaders()

​setViewportSize()

​waitForLoadState()

​waitForTimeout()

​waitForSelector()

​screenshot()

​snapshot()

​tools()

​url()

​title()

​close()

​locator()

​Quick start

​goto()

​reload()

​go_back()

​go_forward()

​click()

​hover()

​scroll()

​drag_and_drop()

​type()

​key_press()

​evaluate()

​on()

​CDPSubscription

​add_init_script()

​set_extra_http_headers()

​set_viewport_size()

​wait_for_load_state()

​wait_for_timeout()

​wait_for_selector()

​screenshot()

​snapshot()

​tools()

​url()

​title()

​close()

​locator()

​Quick start

​Goto()

​Reload()

​GoBack()

​GoForward()

​Click()

​Hover()

​Scroll()

​DragAndDrop()

​Type()

​KeyPress()

​Evaluate()

​On()

​CDPSubscription

​AddInitScript()

​SetExtraHTTPHeaders()

​SetViewportSize()

​WaitForLoadState()

​WaitForTimeout()

​WaitForSelector()

​Screenshot()

​Snapshot()

​Tools()

​URL()

​Title()

​Close()

Quick start

goto()

reload()

goBack()

goForward()

click()

hover()

scroll()

dragAndDrop()

type()

keyPress()

evaluate()

on()

CDPSubscription

addInitScript()

setExtraHTTPHeaders()

setViewportSize()

waitForLoadState()

waitForTimeout()

waitForSelector()

screenshot()

snapshot()

tools()

url()

title()

close()

locator()

Quick start

goto()

reload()

go_back()

go_forward()

click()

hover()

scroll()

drag_and_drop()

type()

key_press()

evaluate()

on()

CDPSubscription

add_init_script()

set_extra_http_headers()

set_viewport_size()

wait_for_load_state()

wait_for_timeout()

wait_for_selector()

screenshot()

snapshot()

tools()

url()

title()

close()

locator()

Quick start

Goto()

Reload()

GoBack()

GoForward()

Click()

Hover()

Scroll()

DragAndDrop()

Type()

KeyPress()

Evaluate()

On()

CDPSubscription

AddInitScript()

SetExtraHTTPHeaders()

SetViewportSize()

WaitForLoadState()

WaitForTimeout()

WaitForSelector()

Screenshot()

Snapshot()

Tools()

URL()

Title()

Close()