Browser RuntimeStagehand

Stagehand Locator

View as Markdown

All Locator methods available when using the Stagehand driver.

Access via runtime.page.locator(...) after launching a Stagehand runtime.

Every method below is a remote call. The SDK translates it into a structured step sent to a single endpoint:

POST /v1/workspaces/{workspaceId}/execute
1{
2  "runtime": "my-browser",
3  "steps": [
4    {
5      "call": "locator.goto",
6      "args": ["https://example.com"]
7    }
8  ]
9}

The call field maps directly to the method name. args is a JSON array of the method’s arguments. You can batch multiple steps in one request.

Actions

click(options?)

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)
1await locator.click();
ParameterTypeRequiredDescription
optionsStagehandLocatorClickOptionsNo—

Upstream docs

fill(value)

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
1await locator.fill("[email protected]");
ParameterTypeRequiredDescription
valuestringYesThe text value to fill into the element.

Upstream docs

type(text, options?)

Type text into the element with optional delay between keystrokes.

If delay is not specified, uses Input.insertText for efficiency.

1await locator.type("Hello");
ParameterTypeRequiredDescription
textstringYesThe text to type.
optionsStagehandLocatorTypeOptionsNo—

Upstream docs

hover()

Move the mouse cursor to the element’s center without clicking.

Scrolls the element into view and dispatches a mouse move event.

1await locator.hover();

Upstream docs

selectOption(values)

Select one or more options in a <select> element.

For multi-select elements, pass an array of values.

1await locator.selectOption("blue");
ParameterTypeRequiredDescription
valuesstring | string[]YesOption value(s) to select.

Returns string[] — Array of values that were actually selected.

Upstream docs

setInputFiles(files)

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.

1await locator.setInputFiles("./file.pdf");
ParameterTypeRequiredDescription
filesStagehandFileInputYesFile paths or file payloads to upload.

Upstream docs

highlight(options?)

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
1await locator.highlight();
ParameterTypeRequiredDescription
optionsStagehandHighlightOptionsNo—

Upstream docs

scrollTo(percent)

Scroll the element to a specific position.

For <html> or <body> elements, scrolls the window. Otherwise, scrolls the element itself.

1await locator.scrollTo(50); // Scroll to 50%
ParameterTypeRequiredDescription
percentnumber | stringYesScroll position as percentage (0-100).

Upstream docs

centroid()

Get the center coordinates of the element.

1const { x, y } = await locator.centroid();

Returns { x: number; y: number } — Center point in CSS pixels { x, y }.

Upstream docs

sendClickEvent(options?)

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)
1await locator.sendClickEvent();
ParameterTypeRequiredDescription
optionsStagehandSendClickEventOptionsNo—

Upstream docs

Queries

count()

Return the number of elements matching this locator.

1const count = await locator.count();

Returns number

Upstream docs

nth(index)

Return a locator for the nth matching element.

Index is zero-based.

1const secondItem = locator.nth(1);
ParameterTypeRequiredDescription
indexnumberYesZero-based index of the element.

Returns RemoteStagehandLocator

Upstream docs

first()

Return a locator for the first matching element.

1const firstItem = locator.first();

Returns RemoteStagehandLocator

Upstream docs

Content

inputValue()

Get the current value of an input element.

Works with: <input>, <textarea>, <select>, contenteditable elements.

1const value = await locator.inputValue();

Returns string — The element’s input value.

Upstream docs

textContent()

Get the element’s text content (raw).

1const text = await locator.textContent();

Returns string — The element’s textContent property.

Upstream docs

innerText()

Get the element’s visible text (layout-aware).

1const text = await locator.innerText();

Returns string — The element’s innerText property.

Upstream docs

innerHtml()

Get the element’s inner HTML.

1const html = await locator.innerHtml();

Returns string — The element’s innerHTML property.

Upstream docs

backendNodeId()

Get the DOM backend node ID for the element.

Useful for identity comparisons without maintaining element handles.

1const nodeId = await locator.backendNodeId();

Returns number — Unique identifier for the DOM node.

Upstream docs

State Checks

isVisible()

Check if the element is visible.

1const visible = await locator.isVisible();

Returns boolean — true if element is attached and visible.

Upstream docs

isChecked()

Check if a checkbox or radio button is checked.

Also considers aria-checked for ARIA widgets.

1const checked = await locator.isChecked();

Returns boolean — true if checked.

Upstream docs