***

title: Stagehand Locator
description: Complete Locator method reference for the Stagehand driver.
------------------------------------------------------------------------

All `Locator` methods available when using the **Stagehand** driver.

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

<Accordion title="How these methods work over HTTP">
  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
  ```

  ```json
  {
    "runtime": "my-browser",
    "steps": [
      {
        "call": "locator.goto",
        "args": ["https://example.com"]
      }
    ]
  }
  ```

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

## Actions

### click(options?)

Click the element at its visual center.

<Note>
  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)
</Note>

```ts
await locator.click();
```

| Parameter | Type                           | Required | Description |
| --------- | ------------------------------ | -------- | ----------- |
| `options` | `StagehandLocatorClickOptions` | No       | —           |

[Upstream docs](https://docs.stagehand.dev/references/locator#click)

***

### fill(value)

Fill an input, textarea, or contenteditable element.

<Note>
  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
</Note>

```ts
await locator.fill("user@example.com");
```

| Parameter | Type     | Required | Description                              |
| --------- | -------- | -------- | ---------------------------------------- |
| `value`   | `string` | Yes      | The text value to fill into the element. |

[Upstream docs](https://docs.stagehand.dev/references/locator#fill)

***

### type(text, options?)

Type text into the element with optional delay between keystrokes.

<Note>
  If delay is not specified, uses Input.insertText for efficiency.
</Note>

```ts
await locator.type("Hello");
```

| Parameter | Type                          | Required | Description       |
| --------- | ----------------------------- | -------- | ----------------- |
| `text`    | `string`                      | Yes      | The text to type. |
| `options` | `StagehandLocatorTypeOptions` | No       | —                 |

[Upstream docs](https://docs.stagehand.dev/references/locator#type)

***

### hover()

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

<Note>
  Scrolls the element into view and dispatches a mouse move event.
</Note>

```ts
await locator.hover();
```

[Upstream docs](https://docs.stagehand.dev/references/locator#hover)

***

### selectOption(values)

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

<Note>
  For multi-select elements, pass an array of values.
</Note>

```ts
await locator.selectOption("blue");
```

| Parameter | Type                 | Required | Description                |
| --------- | -------------------- | -------- | -------------------------- |
| `values`  | `string \| string[]` | Yes      | Option value(s) to select. |

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

[Upstream docs](https://docs.stagehand.dev/references/locator#selectoption)

***

### setInputFiles(files)

Set files on an \<input type="file"> element.

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

```ts
await locator.setInputFiles("./file.pdf");
```

| Parameter | Type                 | Required | Description                            |
| --------- | -------------------- | -------- | -------------------------------------- |
| `files`   | `StagehandFileInput` | Yes      | File paths or file payloads to upload. |

[Upstream docs](https://docs.stagehand.dev/references/locator#setinputfiles)

***

### highlight(options?)

Visually highlight the element with an overlay.

<Note>
  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
</Note>

```ts
await locator.highlight();
```

| Parameter | Type                        | Required | Description |
| --------- | --------------------------- | -------- | ----------- |
| `options` | `StagehandHighlightOptions` | No       | —           |

[Upstream docs](https://docs.stagehand.dev/references/locator#highlight)

***

### scrollTo(percent)

Scroll the element to a specific position.

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

```ts
await locator.scrollTo(50); // Scroll to 50%
```

| Parameter | Type               | Required | Description                            |
| --------- | ------------------ | -------- | -------------------------------------- |
| `percent` | `number \| string` | Yes      | Scroll position as percentage (0-100). |

[Upstream docs](https://docs.stagehand.dev/references/locator#scrollto)

***

### centroid()

Get the center coordinates of the element.

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

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

[Upstream docs](https://docs.stagehand.dev/references/locator#centroid)

***

### sendClickEvent(options?)

Dispatch a DOM click event directly on the element.

<Note>
  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)
</Note>

```ts
await locator.sendClickEvent();
```

| Parameter | Type                             | Required | Description |
| --------- | -------------------------------- | -------- | ----------- |
| `options` | `StagehandSendClickEventOptions` | No       | —           |

[Upstream docs](https://docs.stagehand.dev/references/locator#sendclickevent)

***

## Queries

### count()

Return the number of elements matching this locator.

```ts
const count = await locator.count();
```

**Returns** `number`

[Upstream docs](https://docs.stagehand.dev/references/locator#count)

***

### nth(index)

Return a locator for the nth matching element.

<Note>
  Index is zero-based.
</Note>

```ts
const secondItem = locator.nth(1);
```

| Parameter | Type     | Required | Description                      |
| --------- | -------- | -------- | -------------------------------- |
| `index`   | `number` | Yes      | Zero-based index of the element. |

**Returns** `RemoteStagehandLocator`

[Upstream docs](https://docs.stagehand.dev/references/locator#nth)

***

### first()

Return a locator for the first matching element.

```ts
const firstItem = locator.first();
```

**Returns** `RemoteStagehandLocator`

[Upstream docs](https://docs.stagehand.dev/references/locator#first)

***

## Content

### inputValue()

Get the current value of an input element.

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

```ts
const value = await locator.inputValue();
```

**Returns** `string`
— The element's input value.

[Upstream docs](https://docs.stagehand.dev/references/locator#inputvalue)

***

### textContent()

Get the element's text content (raw).

```ts
const text = await locator.textContent();
```

**Returns** `string`
— The element's textContent property.

[Upstream docs](https://docs.stagehand.dev/references/locator#textcontent)

***

### innerText()

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

```ts
const text = await locator.innerText();
```

**Returns** `string`
— The element's innerText property.

[Upstream docs](https://docs.stagehand.dev/references/locator#innertext)

***

### innerHtml()

Get the element's inner HTML.

```ts
const html = await locator.innerHtml();
```

**Returns** `string`
— The element's innerHTML property.

[Upstream docs](https://docs.stagehand.dev/references/locator#innerhtml)

***

### backendNodeId()

Get the DOM backend node ID for the element.

<Note>
  Useful for identity comparisons without maintaining element handles.
</Note>

```ts
const nodeId = await locator.backendNodeId();
```

**Returns** `number`
— Unique identifier for the DOM node.

[Upstream docs](https://docs.stagehand.dev/references/locator#backendnodeid)

***

## State Checks

### isVisible()

Check if the element is visible.

```ts
const visible = await locator.isVisible();
```

**Returns** `boolean`
— true if element is attached and visible.

[Upstream docs](https://docs.stagehand.dev/references/locator#isvisible)

***

### isChecked()

Check if a checkbox or radio button is checked.

<Note>
  Also considers aria-checked for ARIA widgets.
</Note>

```ts
const checked = await locator.isChecked();
```

**Returns** `boolean`
— true if checked.

[Upstream docs](https://docs.stagehand.dev/references/locator#ischecked)

***