Skip to main content
Locator methods for the Stagehand driver.

​
Actions

​
click

Click the element at its visual center.
The method:
  1. Scrolls element into view
  2. Gets element geometry
  3. Moves mouse to center
  4. Dispatches mousePressed and mouseReleased events
Options include:
  • button: ‘left’ | ‘right’ | ‘middle’ (default: ‘left’)
  • clickCount: Number of clicks (default: 1)
Upstream docs
​
options
StagehandLocatorClickOptions
await locator.click();

​
fill

Fill an input, textarea, or contenteditable element.
The method intelligently handles different input types:
  • Uses native value setter for special inputs (date, number, etc.)
  • Types text character-by-character for regular inputs
  • Clears existing content before filling
Upstream docs
​
value
string
required
The text value to fill into the element.
await locator.fill('...');

​
type

Type text into the element with optional delay between keystrokes.
If delay is not specified, uses Input.insertText for efficiency.
Upstream docs
​
text
string
required
The text to type.
​
options
StagehandLocatorTypeOptions
await locator.type('...');

​
hover

Move the mouse cursor to the element’s center without clicking.
Scrolls the element into view and dispatches a mouse move event.
Upstream docs 
await locator.hover();

​
selectOption

Select one or more options in a <select> element.
For multi-select elements, pass an array of values.
Upstream docs
​
values
string | string[]
required
Option value(s) to select.
​
result
string[]
Return value
await locator.selectOption(/* string | string[] */);

​
setInputFiles

Set files on an <input type=“file”> element.
Accepts:
  • File path (string)
  • Array of file paths
  • File payload object { name, mimeType, buffer }
  • Array of file payloads
Pass an empty array to clear the file selection.
Upstream docs
​
files
StagehandFileInput
required
File paths or file payloads to upload.
await locator.setInputFiles(/* StagehandFileInput */);

​
Queries

​
count

Return the number of elements matching this locator. Upstream docs
​
result
number
Return value
await locator.count();

​
nth

Return a locator for the nth matching element.
Index is zero-based.
Upstream docs
​
index
number
required
Zero-based index of the element.
​
result
RemoteStagehandLocator
Return value
await locator.nth(0);

​
first

Return a locator for the first matching element. Upstream docs
​
result
RemoteStagehandLocator
Return value
await locator.first();

​
Content

​
inputValue

Get the current value of an input element.
Works with: <input>, <textarea>, <select>, contenteditable elements.
Upstream docs
​
result
string
Return value
await locator.inputValue();

​
textContent

Get the element’s text content (raw). Upstream docs
​
result
string
Return value
await locator.textContent();

​
innerText

Get the element’s visible text (layout-aware). Upstream docs
​
result
string
Return value
await locator.innerText();

​
innerHtml

Get the element’s inner HTML. Upstream docs
​
result
string
Return value
await locator.innerHtml();

​
State Checks

​
isVisible

Check if the element is visible. Upstream docs
​
result
boolean
Return value
await locator.isVisible();

​
isChecked

Check if a checkbox or radio button is checked.
Also considers aria-checked for ARIA widgets.
Upstream docs
​
result
boolean
Return value
await locator.isChecked();

​
Other

​
highlight

Visually highlight the element with an overlay.
Useful for debugging and visual verification.Options include:
  • durationMs: How long to display the highlight (default: 800)
  • borderColor: Border color RGBA values
  • contentColor: Content fill color RGBA values
Upstream docs
​
options
StagehandHighlightOptions
await locator.highlight();

​
scrollTo

Scroll the element to a specific position.
For <html> or <body> elements, scrolls the window. Otherwise, scrolls the element itself.
Upstream docs
​
percent
number | string
required
Scroll position as percentage (0-100).
await locator.scrollTo(/* number | string */);

​
centroid

Get the center coordinates of the element. Upstream docs
​
result
{ x: number; y: number }
Return value
await locator.centroid();

​
backendNodeId

Get the DOM backend node ID for the element.
Useful for identity comparisons without maintaining element handles.
Upstream docs
​
result
number
Return value
await locator.backendNodeId();

​
sendClickEvent

Dispatch a DOM click event directly on the element.
This dispatches an event directly without synthesizing real pointer input. Useful for elements that rely on click handlers without needing hit-testing.Options include:
  • bubbles: Whether the event bubbles (default: true)
  • cancelable: Whether the event is cancelable (default: true)
  • composed: Whether the event crosses shadow DOM boundaries (default: true)
  • detail: Click count detail (default: 1)
Upstream docs
​
options
StagehandSendClickEventOptions
await locator.sendClickEvent();