locator - Stagehand

Create a Locator from a page selector, then reuse it for element interactions and state queries. first() and nth() refine the local locator descriptor; the resulting descriptor is sent with later operations. Selectors pierce shadow DOM, including closed roots. Selectors also cross iframe boundaries. Separate a frame from a target inside it with >>, and Stagehand resolves each hop in turn, so page.locator("iframe#checkout >> button.submit") reaches the button inside that iframe. Chain as many hops as the page nests. A deep XPath that steps through an iframe resolves the same way, as in /html/body/iframe[2]//div.

Closed roots require a navigated page. Stagehand resolves elements inside iframes and shadow DOMs for you, so you rarely need to target nested documents manually. This relies on privileged browser APIs that aren’t available on about:blank or data: URLs, so navigate to a http: or https: URL first when a target sits inside an iframe or a closed shadow root (see locator limitations).

TypeScript
Python
Go

Quick start

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

Each locator call has a 20-second timeout covering frame readiness, element lookup, & the action itself. Typing delays & highlight duration count toward the same budget. File reading in the SDK & request delivery happen before that budget starts. A timeout stops further steps; it cannot undo browser commands already sent.

await locator.click({ timeout: 5000 });
await locator.fill("hello", { timeout: 5000 });
const count = await locator.count({ timeout: 0 }); // no timeout

click()

Click the element matched by this locator.

await locator.click();

LocatorClickOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

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 over the matched element.

await locator.hover();

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<void>

Resolves after the operation completes.

fill()

Replace the matched input’s value.

await locator.fill("Browserbase");

string

The value to set.

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<void>

Resolves after the operation completes.

count()

Count the elements matched by this locator.

const count = await locator.count();

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<number>

The operation result.

isChecked()

Check whether the matched control is checked.

const checked = await locator.isChecked();

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<boolean>

The operation result.

inputValue()

Return the current value of the matched input.

const value = await locator.inputValue();

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<string>

The operation result.

isVisible()

Check whether the matched element is visible.

const visible = await locator.isVisible();

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<boolean>

The operation result.

innerText()

Return the rendered text inside the matched element.

const text = await locator.innerText();

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<string>

The operation result.

innerHtml()

Return the HTML inside the matched element.

const html = await locator.innerHtml();

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<string>

The operation result.

textContent()

Return the text content of the matched element.

const text = await locator.textContent();

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<string>

The operation result.

scrollTo()

Scroll the matched element to a percentage of its range.

await locator.scrollTo(50);

number | string

A percentage from 0 to 100, optionally expressed as a percentage string.

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<void>

Resolves after the operation completes.

centroid()

Return the center point of the matched element.

const point = await locator.centroid();

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<LocatorCentroidResult>

The operation result.

number

The horizontal center coordinate.

number

The vertical center coordinate.

highlight()

Temporarily highlight the matched element.

await locator.highlight();

LocatorHighlightOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

RgbaColor

The highlight border color.

number

The alpha channel.

number

The blue channel.

number

The green channel.

number

The red channel.

RgbaColor

The highlight fill color.

number

The alpha channel.

number

The blue channel.

number

The green channel.

number

The red channel.

number

How long to display the highlight.

Promise<void>

Resolves after the operation completes.

sendClickEvent()

Dispatch a DOM click event on the matched element.

await locator.sendClickEvent();

LocatorSendClickEventOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

boolean

Whether the event bubbles.

boolean

Whether the event can be canceled.

boolean

Whether the event crosses shadow DOM boundaries.

number

The event-specific click detail.

Promise<void>

Resolves after the operation completes.

type()

Type text into the matched element.

await locator.type("Browserbase");

string

The text to type.

LocatorTypeOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

number

The input delay in milliseconds.

Promise<void>

Resolves after the operation completes.

selectOption()

Select one or more values in the matched select element.

const values = await locator.selectOption("us");

string | string[]

The value or values to select.

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<string[]>

The operation result.

setInputFiles()

Set one or more local files or in-memory payloads on the matched <input type="file">. The SDK resolves relative paths on the caller’s machine. Pass an empty array to clear the selection.

await page.locator('input[type="file"]').setInputFiles("./resume.pdf");

FileInput

Local file path(s) or in-memory payload(s) to upload. The SDK serializes each file in memory and limits it to 50 MiB.

string

The filename exposed to the page.

string

The file’s MIME type.

ArrayBuffer | Uint8Array | string

The in-memory file content to upload. The SDK base64-encodes it for transport.

number

The file’s last-modified time in Unix milliseconds.

LocatorOptions

Options that configure this operation.

number

The timeout for the whole call in milliseconds. Defaults to 20,000. Set to 0 to disable it.

Promise<void>

Resolves after the files are attached.

first()

Create a locator for the first matching element.

const first = locator.first();

Locator

The operation result.

nth()

Create a locator for a matching element at a zero-based index.

const third = locator.nth(2);

number

The zero-based match index.

Locator

The operation result.

Quick start

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

Timeouts cover frame readiness, element lookup, & the action, including typing delays & highlight duration. File reading in the SDK & request delivery happen before the execution budget starts. Canceling the Python task stops the client waiting; it does not cancel work already sent to the browser.

await locator.click(timeout=5000)
await locator.fill("hello", timeout=5000)
count = await locator.count(timeout=0)  # no timeout

click()

Click the element matched by this locator.

await locator.click()

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

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

int | None

The number of clicks to dispatch.

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

None

Resolves after the operation completes.

hover()

Move the pointer over the matched element.

await locator.hover()

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

None

Resolves after the operation completes.

fill()

Replace the matched input’s value.

await locator.fill("Browserbase")

str

The value to set.

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

None

Resolves after the operation completes.

count()

Count the elements matched by this locator.

count = await locator.count()

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

int

The operation result.

is_checked()

Check whether the matched control is checked.

checked = await locator.is_checked()

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

bool

The operation result.

input_value()

Return the current value of the matched input.

value = await locator.input_value()

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

str

The operation result.

is_visible()

Check whether the matched element is visible.

visible = await locator.is_visible()

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

bool

The operation result.

inner_text()

Return the rendered text inside the matched element.

text = await locator.inner_text()

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

str

The operation result.

inner_html()

Return the HTML inside the matched element.

html = await locator.inner_html()

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

str

The operation result.

text_content()

Return the text content of the matched element.

text = await locator.text_content()

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

str

The operation result.

scroll_to()

Scroll the matched element to a percentage of its range.

await locator.scroll_to(50)

float | str

A percentage from 0 to 100, optionally expressed as a percentage string.

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

None

Resolves after the operation completes.

centroid()

Return the center point of the matched element.

point = await locator.centroid()

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

LocatorCentroidResult

The operation result.

float

The horizontal center coordinate.

float

The vertical center coordinate.

highlight()

Temporarily highlight the matched element.

await locator.highlight(duration_ms=1000)

int | None

How long to display the highlight.

RgbaColor | None

The highlight border color.

float

The alpha channel.

float

The blue channel.

float

The green channel.

float

The red channel.

RgbaColor | None

The highlight fill color.

float

The alpha channel.

float

The blue channel.

float

The green channel.

float

The red channel.

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

None

Resolves after the operation completes.

send_click_event()

Dispatch a DOM click event on the matched element.

await locator.send_click_event()

bool | None

Whether the event bubbles.

bool | None

Whether the event can be canceled.

bool | None

Whether the event crosses shadow DOM boundaries.

float | None

Event-specific click detail.

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

None

Resolves after the operation completes.

type()

Type text into the matched element.

await locator.type("Browserbase")

str

The text to type.

float | None

Delay between keystrokes, in milliseconds.

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

None

Resolves after the operation completes.

select_option()

Select one or more values in the matched select element.

values = await locator.select_option("us")

str | Sequence[str]

The value or values to select.

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

list[str]

The operation result.

set_input_files()

Set one or more local files or in-memory payloads on the matched <input type="file">. The SDK resolves relative paths on the caller’s machine. Pass an empty sequence to clear the selection.

await page.locator('input[type="file"]').set_input_files("./resume.pdf")

Local file path(s) or in-memory payload(s) to upload. The SDK serializes each file in memory and limits it to 50 MiB.

str

The filename exposed to the page.

str

The file’s MIME type.

bytes | bytearray | memoryview | str

The in-memory file content to upload. The SDK base64-encodes it for transport.

int

The file’s last-modified time in Unix milliseconds.

float | None

The timeout for the whole call in milliseconds. Omit it or pass None for the 20,000 ms default. Set to 0 to disable it.

None

Resolves after the files are attached.

first()

Create a locator for the first matching element.

first = locator.first()

Self

The operation result.

nth()

Create a locator for a matching element at a zero-based index.

third = locator.nth(2)

int

The zero-based match index.

Self

The operation result.

Quick start

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

Go locators use *stagehand.PageLocator. Actions & reads take a context.Context first. Methods like Fill & Count accept one optional *stagehand.LocatorOptions; omit it or pass nil for defaults. For methods like Click & Type, set Timeout in their existing options.The default timeout is 20 seconds. Set Timeout to a pointer to a number of milliseconds, or a pointer to 0 for no timeout.The same timeout covers waiting for frames, finding the element, & performing the action. Typing delays & highlight duration count toward it. Reading upload files & sending the request do not.Your context can stop the client waiting sooner, but it does not cancel work already sent to the browser.

timeout := 5000.0
if err := locator.Fill(ctx, "hello", &stagehand.LocatorOptions{Timeout: &timeout}); err != nil {
    return err
}
unlimited := 0.0
count, err := locator.Count(ctx, &stagehand.LocatorOptions{Timeout: &unlimited})
if err != nil {
    return err
}
fmt.Println(count)

Click()

Click the element matched by this locator.

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

*LocatorClickOptions

Options that configure this operation. Pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

*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 over the matched element.

if err := locator.Hover(ctx); err != nil {
    return err
}

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

error

Returns nil after the operation completes.

Fill()

Replace the matched input’s value.

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

string

The value to set.

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

error

Returns nil after the operation completes.

Count()

Count the elements matched by this locator.

count, err := locator.Count(ctx)
if err != nil {
    return err
}
fmt.Println(count)

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

(int, error)

The operation result.

IsChecked()

Check whether the matched control is checked.

checked, err := locator.IsChecked(ctx)
if err != nil {
    return err
}
fmt.Println(checked)

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

(bool, error)

The operation result.

InputValue()

Return the current value of the matched input.

value, err := locator.InputValue(ctx)
if err != nil {
    return err
}
fmt.Println(value)

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

(string, error)

The operation result.

IsVisible()

Check whether the matched element is visible.

visible, err := locator.IsVisible(ctx)
if err != nil {
    return err
}
fmt.Println(visible)

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

(bool, error)

The operation result.

InnerText()

Return the rendered text inside the matched element.

text, err := locator.InnerText(ctx)
if err != nil {
    return err
}
fmt.Println(text)

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

(string, error)

The operation result.

InnerHTML()

Return the HTML inside the matched element.

html, err := locator.InnerHTML(ctx)
if err != nil {
    return err
}
fmt.Println(html)

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

(string, error)

The operation result.

TextContent()

Return the text content of the matched element.

text, err := locator.TextContent(ctx)
if err != nil {
    return err
}
fmt.Println(text)

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

(string, error)

The operation result.

ScrollTo()

Scroll the matched element to a percentage of its range.

if err := locator.ScrollTo(ctx, stagehand.NumericScrollPercent(50)); err != nil {
    return err
}

ScrollPercent

A percentage from 0 to 100. Construct it with stagehand.NumericScrollPercent(50), or with stagehand.NamedScrollPercent("50%") for a percentage string.

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

error

Returns nil after the operation completes.

Centroid()

Return the center point of the matched element.

point, err := locator.Centroid(ctx)
if err != nil {
    return err
}
fmt.Println(point.X, point.Y)

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

(LocatorCentroidResult, error)

The operation result.

float64

The horizontal center coordinate.

float64

The vertical center coordinate.

Highlight()

Temporarily highlight the matched element.

durationMs := 1000
err := locator.Highlight(ctx, &stagehand.LocatorHighlightOptions{DurationMs: &durationMs})
if err != nil {
    return err
}

*LocatorHighlightOptions

Options that configure this operation. Pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

*RgbaColor

The highlight border color.

*float64

The alpha channel.

float64

The blue channel.

float64

The green channel.

float64

The red channel.

*RgbaColor

The highlight fill color.

*float64

The alpha channel.

float64

The blue channel.

float64

The green channel.

float64

The red channel.

*int

How long to display the highlight.

error

Returns nil after the operation completes.

SendClickEvent()

Dispatch a DOM click event on the matched element.

if err := locator.SendClickEvent(ctx, nil); err != nil {
    return err
}

*LocatorSendClickEventOptions

Options that configure this operation. Pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

*bool

Whether the event bubbles.

*bool

Whether the event can be canceled.

*bool

Whether the event crosses shadow DOM boundaries.

*float64

The event-specific click detail.

error

Returns nil after the operation completes.

Type()

Type text into the matched element.

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

string

The text to type.

*LocatorTypeOptions

Options that configure this operation. Pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

*float64

The input delay in milliseconds.

error

Returns nil after the operation completes.

SelectOption()

Select one or more values in the matched select element.

values, err := locator.SelectOption(ctx, stagehand.StringList{"us"})
if err != nil {
    return err
}
fmt.Println(values)

StringList

The value or values to select. StringList is a []string.

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

([]string, error)

The operation result.

SetInputFiles()

Set local files or in-memory payloads on the matched <input type="file">. Pass files as a slice; nil or an empty slice clears the selection. The SDK resolves relative paths on the caller’s machine. Omit options to use the default timeout.

timeout := 5000.0
err := page.Locator(`input[type="file"]`).SetInputFiles(
    ctx,
    []stagehand.FileInput{stagehand.FilePath("./resume.pdf")},
    &stagehand.LocatorOptions{Timeout: &timeout},
)
if err != nil {
    return err
}

...*LocatorOptions

Optional settings for this call. Pass at most one options value; omit it or pass nil for defaults.

*float64

The timeout for the whole call in milliseconds. A nil field uses the 20,000 ms default; a pointer to 0 disables it.

[]FileInput

Local file path(s) or in-memory payload(s) to upload. Construct each with stagehand.FilePath(path) or stagehand.FileData(name, mimeType, buffer). The SDK serializes each file in memory and limits it to 50 MiB.

string

A path on the SDK caller’s filesystem. Cannot be combined with the payload fields.

string

The filename exposed to the page.

string

The file’s MIME type.

[]byte

The in-memory file content to upload. The SDK base64-encodes it for transport.

*int64

The file’s last-modified time in Unix milliseconds.

error

Returns nil after the files are attached.

First()

Create a locator for the first matching element.

first := locator.First()
if err := first.Click(ctx, nil); err != nil {
    return err
}

*PageLocator

The operation result.

Nth()

Create a locator for a matching element at a zero-based index. Returns an error when the index is negative.

third, err := locator.Nth(2)
if err != nil {
    return err
}
if err := third.Click(ctx, nil); err != nil {
    return err
}

int

The zero-based match index.

(*PageLocator, error)

The operation result.

​Quick start

​click()

​hover()

​fill()

​count()

​isChecked()

​inputValue()

​isVisible()

​innerText()

​innerHtml()

​textContent()

​scrollTo()

​centroid()

​highlight()

​sendClickEvent()

​type()

​selectOption()

​setInputFiles()

​first()

​nth()

​Quick start

​click()

​hover()

​fill()

​count()

​is_checked()

​input_value()

​is_visible()

​inner_text()

​inner_html()

​text_content()

​scroll_to()

​centroid()

​highlight()

​send_click_event()

​type()

​select_option()

​set_input_files()

​first()

​nth()

​Quick start

​Click()

​Hover()

​Fill()

​Count()

​IsChecked()

​InputValue()

​IsVisible()

​InnerText()

​InnerHTML()

​TextContent()

​ScrollTo()

​Centroid()

​Highlight()

​SendClickEvent()

​Type()

​SelectOption()

​SetInputFiles()

​First()

​Nth()

Quick start

click()

hover()

fill()

count()

isChecked()

inputValue()

isVisible()

innerText()

innerHtml()

textContent()

scrollTo()

centroid()

highlight()

sendClickEvent()

type()

selectOption()

setInputFiles()

first()

nth()

Quick start

click()

hover()

fill()

count()

is_checked()

input_value()

is_visible()

inner_text()

inner_html()

text_content()

scroll_to()

centroid()

highlight()

send_click_event()

type()

select_option()

set_input_files()

first()

nth()

Quick start

Click()

Hover()

Fill()

Count()

IsChecked()

InputValue()

IsVisible()

InnerText()

InnerHTML()

TextContent()

ScrollTo()

Centroid()

Highlight()

SendClickEvent()

Type()

SelectOption()

SetInputFiles()

First()

Nth()