> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stagehand.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# locator
> Target elements and perform focused DOM interactions
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](/v4/reference/locator)).
## Quick start
```typescript theme={null}
const locator = page.locator("button[type=submit]");
await locator.click();
```
## click()
Click the element matched by this locator.
```typescript theme={null}
await locator.click();
```
Options that configure this operation.
The mouse button to use: `"left"`, `"middle"`, or `"right"`.
The number of clicks to dispatch.
Resolves after the operation completes.
## hover()
Move the pointer over the matched element.
```typescript theme={null}
await locator.hover();
```
Resolves after the operation completes.
## fill()
Replace the matched input's value.
```typescript theme={null}
await locator.fill("Browserbase");
```
The value to set.
Resolves after the operation completes.
## count()
Count the elements matched by this locator.
```typescript theme={null}
const count = await locator.count();
```
The operation result.
## isChecked()
Check whether the matched control is checked.
```typescript theme={null}
const checked = await locator.isChecked();
```
The operation result.
## inputValue()
Return the current value of the matched input.
```typescript theme={null}
const value = await locator.inputValue();
```
The operation result.
## isVisible()
Check whether the matched element is visible.
```typescript theme={null}
const visible = await locator.isVisible();
```
The operation result.
## innerText()
Return the rendered text inside the matched element.
```typescript theme={null}
const text = await locator.innerText();
```
The operation result.
## innerHtml()
Return the HTML inside the matched element.
```typescript theme={null}
const html = await locator.innerHtml();
```
The operation result.
## textContent()
Return the text content of the matched element.
```typescript theme={null}
const text = await locator.textContent();
```
The operation result.
## scrollTo()
Scroll the matched element to a percentage of its range.
```typescript theme={null}
await locator.scrollTo(50);
```
A percentage from 0 to 100, optionally expressed as a percentage string.
Resolves after the operation completes.
## centroid()
Return the center point of the matched element.
```typescript theme={null}
const point = await locator.centroid();
```
The operation result.
The horizontal center coordinate.
The vertical center coordinate.
## highlight()
Temporarily highlight the matched element.
```typescript theme={null}
await locator.highlight();
```
Options that configure this operation.
The highlight border color.
The alpha channel.
The blue channel.
The green channel.
The red channel.
The highlight fill color.
The alpha channel.
The blue channel.
The green channel.
The red channel.
How long to display the highlight.
Resolves after the operation completes.
## sendClickEvent()
Dispatch a DOM click event on the matched element.
```typescript theme={null}
await locator.sendClickEvent();
```
Options that configure this operation.
Whether the event bubbles.
Whether the event can be canceled.
Whether the event crosses shadow DOM boundaries.
The event-specific click detail.
Resolves after the operation completes.
## type()
Type text into the matched element.
```typescript theme={null}
await locator.type("Browserbase");
```
The text to type.
Options that configure this operation.
The input delay in milliseconds.
Resolves after the operation completes.
## selectOption()
Select one or more values in the matched select element.
```typescript theme={null}
const values = await locator.selectOption("us");
```
The value or values to select.
The operation result.
## setInputFiles()
Set one or more local files or in-memory payloads on the matched ``. The SDK resolves relative paths on the caller's machine. Pass an empty array to clear the selection.
```typescript theme={null}
await page.locator('input[type="file"]').setInputFiles("./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.
The filename exposed to the page.
The file's MIME type.
The in-memory file content to upload. The SDK base64-encodes it for transport.
The file's last-modified time in Unix milliseconds.
Resolves after the files are attached.
## first()
Create a locator for the first matching element.
```typescript theme={null}
const first = locator.first();
```
The operation result.
## nth()
Create a locator for a matching element at a zero-based index.
```typescript theme={null}
const third = locator.nth(2);
```
The zero-based match index.
The operation result.
## Quick start
```python theme={null}
locator = page.locator("button[type=submit]")
await locator.click()
```
## click()
Click the element matched by this locator.
```python theme={null}
await locator.click()
```
The mouse button to use: `"left"`, `"middle"`, or `"right"`.
The number of clicks to dispatch.
Resolves after the operation completes.
## hover()
Move the pointer over the matched element.
```python theme={null}
await locator.hover()
```
Resolves after the operation completes.
## fill()
Replace the matched input's value.
```python theme={null}
await locator.fill("Browserbase")
```
The value to set.
Resolves after the operation completes.
## count()
Count the elements matched by this locator.
```python theme={null}
count = await locator.count()
```
The operation result.
## is\_checked()
Check whether the matched control is checked.
```python theme={null}
checked = await locator.is_checked()
```
The operation result.
## input\_value()
Return the current value of the matched input.
```python theme={null}
value = await locator.input_value()
```
The operation result.
## is\_visible()
Check whether the matched element is visible.
```python theme={null}
visible = await locator.is_visible()
```
The operation result.
## inner\_text()
Return the rendered text inside the matched element.
```python theme={null}
text = await locator.inner_text()
```
The operation result.
## inner\_html()
Return the HTML inside the matched element.
```python theme={null}
html = await locator.inner_html()
```
The operation result.
## text\_content()
Return the text content of the matched element.
```python theme={null}
text = await locator.text_content()
```
The operation result.
## scroll\_to()
Scroll the matched element to a percentage of its range.
```python theme={null}
await locator.scroll_to(50)
```
A percentage from 0 to 100, optionally expressed as a percentage string.
Resolves after the operation completes.
## centroid()
Return the center point of the matched element.
```python theme={null}
point = await locator.centroid()
```
The operation result.
The horizontal center coordinate.
The vertical center coordinate.
## highlight()
Temporarily highlight the matched element.
```python theme={null}
await locator.highlight(duration_ms=1000)
```
How long to display the highlight.
The highlight border color.
The alpha channel.
The blue channel.
The green channel.
The red channel.
The highlight fill color.
The alpha channel.
The blue channel.
The green channel.
The red channel.
Resolves after the operation completes.
## send\_click\_event()
Dispatch a DOM click event on the matched element.
```python theme={null}
await locator.send_click_event()
```
Whether the event bubbles.
Whether the event can be canceled.
Whether the event crosses shadow DOM boundaries.
Event-specific click detail.
Resolves after the operation completes.
## type()
Type text into the matched element.
```python theme={null}
await locator.type("Browserbase")
```
The text to type.
Delay between keystrokes, in milliseconds.
Resolves after the operation completes.
## select\_option()
Select one or more values in the matched select element.
```python theme={null}
values = await locator.select_option("us")
```
The value or values to select.
The operation result.
## set\_input\_files()
Set one or more local files or in-memory payloads on the matched ``. The SDK resolves relative paths on the caller's machine. Pass an empty sequence to clear the selection.
```python theme={null}
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.
The filename exposed to the page.
The file's MIME type.
The in-memory file content to upload. The SDK base64-encodes it for transport.
The file's last-modified time in Unix milliseconds.
Resolves after the files are attached.
## first()
Create a locator for the first matching element.
```python theme={null}
first = locator.first()
```
The operation result.
## nth()
Create a locator for a matching element at a zero-based index.
```python theme={null}
third = locator.nth(2)
```
The zero-based match index.
The operation result.
## Quick start
```go theme={null}
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.
```go theme={null}
if err := locator.Click(ctx, nil); err != nil {
return err
}
```
Options that configure this operation. Pass `nil` for defaults.
The mouse button to use: `MouseButtonLeft`, `MouseButtonMiddle`, or `MouseButtonRight`.
The number of clicks to dispatch.
Returns `nil` after the operation completes.
## Hover()
Move the pointer over the matched element.
```go theme={null}
if err := locator.Hover(ctx); err != nil {
return err
}
```
Returns `nil` after the operation completes.
## Fill()
Replace the matched input's value.
```go theme={null}
if err := locator.Fill(ctx, "Browserbase"); err != nil {
return err
}
```
The value to set.
Returns `nil` after the operation completes.
## Count()
Count the elements matched by this locator.
```go theme={null}
count, err := locator.Count(ctx)
if err != nil {
return err
}
fmt.Println(count)
```
The operation result.
## IsChecked()
Check whether the matched control is checked.
```go theme={null}
checked, err := locator.IsChecked(ctx)
if err != nil {
return err
}
fmt.Println(checked)
```
The operation result.
## InputValue()
Return the current value of the matched input.
```go theme={null}
value, err := locator.InputValue(ctx)
if err != nil {
return err
}
fmt.Println(value)
```
The operation result.
## IsVisible()
Check whether the matched element is visible.
```go theme={null}
visible, err := locator.IsVisible(ctx)
if err != nil {
return err
}
fmt.Println(visible)
```
The operation result.
## InnerText()
Return the rendered text inside the matched element.
```go theme={null}
text, err := locator.InnerText(ctx)
if err != nil {
return err
}
fmt.Println(text)
```
The operation result.
## InnerHTML()
Return the HTML inside the matched element.
```go theme={null}
html, err := locator.InnerHTML(ctx)
if err != nil {
return err
}
fmt.Println(html)
```
The operation result.
## TextContent()
Return the text content of the matched element.
```go theme={null}
text, err := locator.TextContent(ctx)
if err != nil {
return err
}
fmt.Println(text)
```
The operation result.
## ScrollTo()
Scroll the matched element to a percentage of its range.
```go theme={null}
if err := locator.ScrollTo(ctx, stagehand.NumericScrollPercent(50)); err != nil {
return err
}
```
A percentage from 0 to 100. Construct it with `stagehand.NumericScrollPercent(50)`, or with `stagehand.NamedScrollPercent("50%")` for a percentage string.
Returns `nil` after the operation completes.
## Centroid()
Return the center point of the matched element.
```go theme={null}
point, err := locator.Centroid(ctx)
if err != nil {
return err
}
fmt.Println(point.X, point.Y)
```
The operation result.
The horizontal center coordinate.
The vertical center coordinate.
## Highlight()
Temporarily highlight the matched element.
```go theme={null}
durationMs := 1000
err := locator.Highlight(ctx, &stagehand.LocatorHighlightOptions{DurationMs: &durationMs})
if err != nil {
return err
}
```
Options that configure this operation. Pass `nil` for defaults.
The highlight border color.
The alpha channel.
The blue channel.
The green channel.
The red channel.
The highlight fill color.
The alpha channel.
The blue channel.
The green channel.
The red channel.
How long to display the highlight.
Returns `nil` after the operation completes.
## SendClickEvent()
Dispatch a DOM click event on the matched element.
```go theme={null}
if err := locator.SendClickEvent(ctx, nil); err != nil {
return err
}
```
Options that configure this operation. Pass `nil` for defaults.
Whether the event bubbles.
Whether the event can be canceled.
Whether the event crosses shadow DOM boundaries.
The event-specific click detail.
Returns `nil` after the operation completes.
## Type()
Type text into the matched element.
```go theme={null}
if err := locator.Type(ctx, "Browserbase", nil); err != nil {
return err
}
```
The text to type.
Options that configure this operation. Pass `nil` for defaults.
The input delay in milliseconds.
Returns `nil` after the operation completes.
## SelectOption()
Select one or more values in the matched select element.
```go theme={null}
values, err := locator.SelectOption(ctx, stagehand.StringList{"us"})
if err != nil {
return err
}
fmt.Println(values)
```
The value or values to select. `StringList` is a `[]string`.
The operation result.
## SetInputFiles()
Set one or more local files or in-memory payloads on the matched ``. The SDK resolves relative paths on the caller's machine. Call it without files to clear the selection.
```go theme={null}
err := page.Locator(`input[type="file"]`).SetInputFiles(ctx, stagehand.FilePath("./resume.pdf"))
if err != nil {
return err
}
```
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.
A path on the SDK caller's filesystem. Cannot be combined with the payload fields.
The filename exposed to the page.
The file's MIME type.
The in-memory file content to upload. The SDK base64-encodes it for transport.
The file's last-modified time in Unix milliseconds.
Returns `nil` after the files are attached.
## First()
Create a locator for the first matching element.
```go theme={null}
first := locator.First()
if err := first.Click(ctx, nil); err != nil {
return err
}
```
The operation result.
## Nth()
Create a locator for a matching element at a zero-based index. Returns an error when the index is negative.
```go theme={null}
third, err := locator.Nth(2)
if err != nil {
return err
}
if err := third.Click(ctx, nil); err != nil {
return err
}
```
The zero-based match index.
The operation result.