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

click()

Click the element matched by this locator.

await locator.click();

LocatorClickOptions

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

await locator.hover();

Promise<void>

Resolves after the operation completes.

fill()

Replace the matched input’s value.

await locator.fill("Browserbase");

string

The value to set.

Promise<void>

Resolves after the operation completes.

count()

Count the elements matched by this locator.

const count = await locator.count();

Promise<number>

The operation result.

isChecked()

Check whether the matched control is checked.

const checked = await locator.isChecked();

Promise<boolean>

The operation result.

inputValue()

Return the current value of the matched input.

const value = await locator.inputValue();

Promise<string>

The operation result.

isVisible()

Check whether the matched element is visible.

const visible = await locator.isVisible();

Promise<boolean>

The operation result.

innerText()

Return the rendered text inside the matched element.

const text = await locator.innerText();

Promise<string>

The operation result.

innerHtml()

Return the HTML inside the matched element.

const html = await locator.innerHtml();

Promise<string>

The operation result.

textContent()

Return the text content of the matched element.

const text = await locator.textContent();

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.

Promise<void>

Resolves after the operation completes.

centroid()

Return the center point of the matched element.

const point = await locator.centroid();

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.

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.

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 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.

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.

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()

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.

None

Resolves after the operation completes.

hover()

Move the pointer over the matched element.

await locator.hover()

None

Resolves after the operation completes.

fill()

Replace the matched input’s value.

await locator.fill("Browserbase")

str

The value to set.

None

Resolves after the operation completes.

count()

Count the elements matched by this locator.

count = await locator.count()

int

The operation result.

is_checked()

Check whether the matched control is checked.

checked = await locator.is_checked()

bool

The operation result.

input_value()

Return the current value of the matched input.

value = await locator.input_value()

str

The operation result.

is_visible()

Check whether the matched element is visible.

visible = await locator.is_visible()

bool

The operation result.

inner_text()

Return the rendered text inside the matched element.

text = await locator.inner_text()

str

The operation result.

inner_html()

Return the HTML inside the matched element.

html = await locator.inner_html()

str

The operation result.

text_content()

Return the text content of the matched element.

text = await locator.text_content()

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.

None

Resolves after the operation completes.

centroid()

Return the center point of the matched element.

point = await locator.centroid()

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.

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.

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.

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.

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.

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
}

In Go the locator type is *stagehand.PageLocator (the wrapper named Locator in the TypeScript and Python SDKs). Every method takes a context.Context first, and methods with options accept a pointer options struct; pass nil for defaults.

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.

*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
}

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.

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)

(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)

(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)

(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)

(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)

(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)

(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)

(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.

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)

(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.

*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.

*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 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.

([]string, error)

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. Call it without files to clear the selection.

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

...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()