***

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

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

Access via `runtime.page.locator(...)` after launching a Playwright 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?)

Clicks on the element.

<Note>
  Waits for actionability checks, scrolls element into view,
  and uses Page.mouse to click in the center of the element.
</Note>

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

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

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-click)

***

### dblclick(options?)

Double-clicks on the element.

<Note>
  Performs two clicks with a short delay, simulating a native double-click.
  Waits for actionability checks before performing the action.
</Note>

```ts
await runtime.page.locator(...).dblclick();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-dblclick)

***

### fill(value, options?)

Fills an input or textarea element with the specified value.

<Note>
  This method waits for actionability checks, focuses the element,
  fills it, and triggers an input event. It clears the existing value before filling.
  Works with \<input>, \<textarea>, and \[contenteditable] elements.
</Note>

```ts
await page.getByLabel('Password').fill('secret');
```

| Parameter | Type                    | Required | Description      |
| --------- | ----------------------- | -------- | ---------------- |
| `value`   | `string`                | Yes      | Value to fill in |
| `options` | `PlaywrightFillOptions` | No       | —                |

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-fill)

***

### clear(options?)

Clears the input field.

<Note>
  Waits for actionability checks, focuses the element,
  clears it, and triggers an input event.
</Note>

```ts
await runtime.page.locator(...).clear();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-clear)

***

### press(key, options?)

Presses a single key or key combination.

<Note>
  Focuses the element, then uses keyboard.down() and keyboard.up().
  Supports modifier keys like Control, Shift, Alt, Meta.
</Note>

```ts
await locator.press('Enter');
```

| Parameter | Type                     | Required | Description                               |
| --------- | ------------------------ | -------- | ----------------------------------------- |
| `key`     | `string`                 | Yes      | Key to press (e.g., "Enter", "Control+A") |
| `options` | `PlaywrightPressOptions` | No       | —                                         |

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-press)

***

### pressSequentially(text, options?)

Types text character by character with keydown, keypress, and keyup events.

<Note>
  Use this for special keyboard handling. In most cases, fill() is preferred.
  The delay option can simulate realistic typing speed.
</Note>

```ts
await locator.pressSequentially('Hello');
```

| Parameter | Type                                 | Required | Description        |
| --------- | ------------------------------------ | -------- | ------------------ |
| `text`    | `string`                             | Yes      | Characters to type |
| `options` | `PlaywrightPressSequentiallyOptions` | No       | —                  |

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-press-sequentially)

***

### type(text, options?)

Types text into the element (DEPRECATED - use fill() or pressSequentially()).

<Note>
  This method is deprecated. Use fill() for most cases,
  or pressSequentially() when special keyboard handling is required.
</Note>

```ts
await runtime.page.locator(...).type('...');
```

| Parameter | Type                                                          | Required | Description |
| --------- | ------------------------------------------------------------- | -------- | ----------- |
| `text`    | `string`                                                      | Yes      | —           |
| `options` | `{ delay?: number; noWaitAfter?: boolean; timeout?: number }` | No       | —           |

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-type)

***

### hover(options?)

Hovers over the element.

<Note>
  Waits for actionability checks, scrolls element into view,
  and moves mouse to the center of the element.
</Note>

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

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

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-hover)

***

### tap(options?)

Performs a tap gesture on the element.

<Note>
  Requires hasTouch option to be enabled in browser context.
  Waits for actionability checks before performing the tap.
</Note>

```ts
await runtime.page.locator(...).tap();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-tap)

***

### focus(options?)

Focuses the element.

```ts
await runtime.page.locator(...).focus();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-focus)

***

### blur(options?)

Removes focus from the element.

```ts
await runtime.page.locator(...).blur();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-blur)

***

### check(options?)

Checks a checkbox or radio button.

<Note>
  If already checked, this method does nothing.
</Note>

```ts
await runtime.page.locator(...).check();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-check)

***

### uncheck(options?)

Unchecks a checkbox.

<Note>
  If already unchecked, this method does nothing.
</Note>

```ts
await runtime.page.locator(...).uncheck();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-uncheck)

***

### setChecked(checked, options?)

Sets the checked state of a checkbox or radio button.

```ts
await runtime.page.locator(...).setChecked(true);
```

| Parameter | Type                          | Required | Description                 |
| --------- | ----------------------------- | -------- | --------------------------- |
| `checked` | `boolean`                     | Yes      | Whether to check or uncheck |
| `options` | `PlaywrightSetCheckedOptions` | No       | —                           |

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-set-checked)

***

### selectOption(values, options?)

Selects option(s) in a \<select> element.

<Note>
  Waits for actionability checks, waits until all options are present,
  and triggers change and input events. Returns array of selected option values.
</Note>

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

| Parameter | Type                                                                                 | Required | Description                                 |
| --------- | ------------------------------------------------------------------------------------ | -------- | ------------------------------------------- |
| `values`  | `string \| string[] \| PlaywrightSelectOptionValue \| PlaywrightSelectOptionValue[]` | Yes      | Options to select by value, label, or index |
| `options` | `PlaywrightSelectOptionOptions`                                                      | No       | —                                           |

**Returns** `string[]`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-select-option)

***

### selectText(options?)

Selects all text content of the element.

<Note>
  This method waits for actionability checks, then focuses the element and selects all text content.
</Note>

```ts
await runtime.page.locator(...).selectText();
```

| Parameter | Type                                    | Required | Description |
| --------- | --------------------------------------- | -------- | ----------- |
| `options` | `{ force?: boolean; timeout?: number }` | No       | —           |

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-select-text)

***

### setInputFiles(files, options?)

Sets files for a file input element.

<Note>
  Pass empty array to clear selected files.
  Supports paths, objects with name/mimeType/buffer, or directories.
</Note>

```ts
await locator.setInputFiles('file.pdf');
```

| Parameter | Type                                                                     | Required | Description                          |
| --------- | ------------------------------------------------------------------------ | -------- | ------------------------------------ |
| `files`   | `string \| string[] \| PlaywrightFilePayload \| PlaywrightFilePayload[]` | Yes      | File paths or file objects to upload |
| `options` | `PlaywrightSetInputFilesOptions`                                         | No       | —                                    |

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-set-input-files)

***

### dragTo(target, options?)

Drags this element to the target element.

<Note>
  Performs mousedown on source, moves to target, and releases with mouseup.
  Supports sourcePosition and targetPosition options for precise control.
</Note>

```ts
await source.dragTo(target);
```

| Parameter | Type                      | Required | Description               |
| --------- | ------------------------- | -------- | ------------------------- |
| `target`  | `RemotePlaywrightLocator` | Yes      | Target locator to drag to |
| `options` | `PlaywrightDragToOptions` | No       | —                         |

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-drag-to)

***

### scrollIntoViewIfNeeded(options?)

Scrolls the element into view if not already visible.

<Note>
  Uses IntersectionObserver to determine if element is already visible.
</Note>

```ts
await runtime.page.locator(...).scrollIntoViewIfNeeded();
```

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

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-scroll-into-view-if-needed)

***

### dispatchEvent(type, eventInit?, options?)

Programmatically dispatches a DOM event on the element.

<Note>
  The event is created as composed, cancelable, and bubbles by default.
  Works regardless of element visibility state.
</Note>

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

| Parameter   | Type                             | Required | Description                                 |
| ----------- | -------------------------------- | -------- | ------------------------------------------- |
| `type`      | `string`                         | Yes      | DOM event type (e.g., "click", "dragstart") |
| `eventInit` | `Record&lt;string, unknown&gt;`  | No       | Event initialization properties             |
| `options`   | `PlaywrightDispatchEventOptions` | No       | —                                           |

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-dispatch-event)

***

### highlight()

Highlights the element on screen (for debugging).

<Note>
  Useful for debugging during test development. Not recommended for production tests.
</Note>

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

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-highlight)

***

## Queries

### count()

Returns the number of elements matching this locator.

<Note>
  For assertions, prefer expect(locator).toHaveCount() to avoid flakiness.
</Note>

```ts
const count = await page.getByRole('listitem').count();
```

**Returns** `number`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-count)

***

### first()

Returns locator to the first matching element.

```ts
runtime.page.locator(...).first();
```

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-first)

***

### last()

Returns locator to the last matching element.

```ts
runtime.page.locator(...).last();
```

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-last)

***

### nth(index)

Returns locator to the nth matching element.

<Note>
  Index is zero-based. Negative indices count from the end (-1 is last).
</Note>

```ts
runtime.page.locator(...).nth(0);
```

| Parameter | Type     | Required | Description      |
| --------- | -------- | -------- | ---------------- |
| `index`   | `number` | Yes      | Zero-based index |

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-nth)

***

### locator(selectorOrLocator, options?)

Creates a locator matching descendants of this element.

<Note>
  Accepts CSS, XPath, or text selectors. Can also accept another locator.
</Note>

```ts
const button = row.locator('button.submit');
```

| Parameter           | Type                                | Required | Description                              |
| ------------------- | ----------------------------------- | -------- | ---------------------------------------- |
| `selectorOrLocator` | `string \| RemotePlaywrightLocator` | Yes      | Selector or locator to match descendants |
| `options`           | `PlaywrightLocatorOptions`          | No       | —                                        |

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-locator)

***

### filter(options?)

Narrows the locator with additional filters.

<Note>
  Supports has, hasNot, hasText, hasNotText, and visible options.
  Multiple filters can be chained.
</Note>

```ts
const row = page.locator('tr').filter({ hasText: 'John' });
```

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

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-filter)

***

### and(locator)

Creates a locator that matches both this locator AND the argument.

<Note>
  Both conditions must be satisfied for an element to match.
</Note>

```ts
const button = page.getByRole('button').and(page.getByTitle('Subscribe'));
```

| Parameter | Type                      | Required | Description                 |
| --------- | ------------------------- | -------- | --------------------------- |
| `locator` | `RemotePlaywrightLocator` | Yes      | Additional locator to match |

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-and)

***

### or(locator)

Creates a locator that matches this locator OR the argument.

<Note>
  Either condition being satisfied will match. Be careful with strict mode -
  if both match, use .first() to select one.
</Note>

```ts
const btnOrLink = page.getByRole('button').or(page.getByRole('link'));
```

| Parameter | Type                      | Required | Description                  |
| --------- | ------------------------- | -------- | ---------------------------- |
| `locator` | `RemotePlaywrightLocator` | Yes      | Alternative locator to match |

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-or)

***

### all()

Returns array of locators pointing to all matching elements.

<Note>
  Does not wait for elements. Use with caution on dynamic lists.
  Wait for the list to stabilize before calling.
</Note>

```ts
for (const li of await page.getByRole('listitem').all()) {
  await li.click();
}
```

**Returns** `RemotePlaywrightLocator[]`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-all)

***

### getByRole(role, options?)

Locates elements by their ARIA role.

<Note>
  Matches by implicit ARIA role (e.g., \<button>) or explicit role attribute.
  Options include name, checked, disabled, expanded, etc.
</Note>

```ts
await locator.getByRole('button', { name: 'Submit' }).click();
```

| Parameter | Type                         | Required | Description        |
| --------- | ---------------------------- | -------- | ------------------ |
| `role`    | `PlaywrightAriaRole`         | Yes      | ARIA role to match |
| `options` | `PlaywrightGetByRoleOptions` | No       | —                  |

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-get-by-role)

***

### getByText(text, options?)

Locates elements containing the specified text.

<Note>
  Matches case-insensitively by default. Use exact: true for exact match.
</Note>

```ts
await locator.getByText('Welcome').click();
```

| Parameter | Type                         | Required | Description              |
| --------- | ---------------------------- | -------- | ------------------------ |
| `text`    | `string \| RegExp`           | Yes      | Text or pattern to match |
| `options` | `PlaywrightGetByTextOptions` | No       | —                        |

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-get-by-text)

***

### getByLabel(text, options?)

Locates form elements by their associated label text.

<Note>
  Matches \<label> text, aria-label, or aria-labelledby.
</Note>

```ts
await locator.getByLabel('Email').fill('test@example.com');
```

| Parameter | Type                          | Required | Description           |
| --------- | ----------------------------- | -------- | --------------------- |
| `text`    | `string \| RegExp`            | Yes      | Label text or pattern |
| `options` | `PlaywrightGetByLabelOptions` | No       | —                     |

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-get-by-label)

***

### getByPlaceholder(text, options?)

Locates input elements by their placeholder text.

```ts
await locator.getByPlaceholder('Search...').fill('query');
```

| Parameter | Type                                | Required | Description                 |
| --------- | ----------------------------------- | -------- | --------------------------- |
| `text`    | `string \| RegExp`                  | Yes      | Placeholder text or pattern |
| `options` | `PlaywrightGetByPlaceholderOptions` | No       | —                           |

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-get-by-placeholder)

***

### getByAltText(text, options?)

Locates elements by their alt attribute (typically images).

```ts
await locator.getByAltText('Company Logo').click();
```

| Parameter | Type                            | Required | Description         |
| --------- | ------------------------------- | -------- | ------------------- |
| `text`    | `string \| RegExp`              | Yes      | Alt text or pattern |
| `options` | `PlaywrightGetByAltTextOptions` | No       | —                   |

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-get-by-alt-text)

***

### getByTitle(text, options?)

Locates elements by their title attribute.

```ts
await locator.getByTitle('More information').click();
```

| Parameter | Type                          | Required | Description                     |
| --------- | ----------------------------- | -------- | ------------------------------- |
| `text`    | `string \| RegExp`            | Yes      | Title attribute text or pattern |
| `options` | `PlaywrightGetByTitleOptions` | No       | —                               |

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-get-by-title)

***

### getByTestId(testId)

Locates elements by their test ID attribute.

<Note>
  Default attribute is data-testid. Can be configured via selectors.setTestIdAttribute().
</Note>

```ts
await locator.getByTestId('submit-button').click();
```

| Parameter | Type               | Required | Description              |
| --------- | ------------------ | -------- | ------------------------ |
| `testId`  | `string \| RegExp` | Yes      | Test ID value or pattern |

**Returns** `RemotePlaywrightLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-get-by-test-id)

***

### contentFrame()

Returns a FrameLocator pointing to the iframe this locator points to.

<Note>
  Useful when you have a Locator to an iframe and want to interact with its content.
</Note>

```ts
const frameLocator = locator.contentFrame();
await frameLocator.getByRole('button').click();
```

**Returns** `RemotePlaywrightFrameLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-content-frame)

***

### frameLocator(selector)

Returns a FrameLocator for an iframe within this element.

<Note>
  Use to interact with content inside iframes.
</Note>

```ts
const frame = locator.frameLocator('iframe.content');
```

| Parameter  | Type     | Required | Description             |
| ---------- | -------- | -------- | ----------------------- |
| `selector` | `string` | Yes      | CSS selector for iframe |

**Returns** `RemotePlaywrightFrameLocator`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-frame-locator)

***

### page()

Returns the Page that this locator belongs to.

```ts
runtime.page.locator(...).page();
```

**Returns** `RemotePlaywrightPage`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-page)

***

## Content

### innerHTML(options?)

Returns the innerHTML of the element.

```ts
await runtime.page.locator(...).innerHTML();
```

| Parameter | Type                   | Required | Description |
| --------- | ---------------------- | -------- | ----------- |
| `options` | `{ timeout?: number }` | No       | —           |

**Returns** `string`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-inner-html)

***

### innerText(options?)

Returns the innerText of the element.

<Note>
  For assertions, prefer expect(locator).toHaveText() with useInnerText option.
</Note>

```ts
await runtime.page.locator(...).innerText();
```

| Parameter | Type                   | Required | Description |
| --------- | ---------------------- | -------- | ----------- |
| `options` | `{ timeout?: number }` | No       | —           |

**Returns** `string`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-inner-text)

***

### textContent(options?)

Returns the textContent of the element.

<Note>
  For assertions, prefer expect(locator).toHaveText().
</Note>

```ts
await runtime.page.locator(...).textContent();
```

| Parameter | Type                   | Required | Description |
| --------- | ---------------------- | -------- | ----------- |
| `options` | `{ timeout?: number }` | No       | —           |

**Returns** `string \| null`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-text-content)

***

### allInnerTexts()

Returns an array of innerText values for all matching elements.

<Note>
  For assertions, prefer expect(locator).toHaveText() with useInnerText option.
</Note>

```ts
const texts = await page.getByRole('link').allInnerTexts();
```

**Returns** `string[]`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-all-inner-texts)

***

### allTextContents()

Returns an array of textContent values for all matching elements.

<Note>
  For assertions, prefer expect(locator).toHaveText().
</Note>

```ts
const texts = await page.getByRole('link').allTextContents();
```

**Returns** `string[]`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-all-text-contents)

***

### getAttribute(name, options?)

Returns the attribute value of the element.

```ts
await runtime.page.locator(...).getAttribute('...');
```

| Parameter | Type                   | Required | Description    |
| --------- | ---------------------- | -------- | -------------- |
| `name`    | `string`               | Yes      | Attribute name |
| `options` | `{ timeout?: number }` | No       | —              |

**Returns** `string \| null`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-get-attribute)

***

### inputValue(options?)

Returns the input value for \<input>, \<textarea>, or \<select> elements.

```ts
await runtime.page.locator(...).inputValue();
```

| Parameter | Type                   | Required | Description |
| --------- | ---------------------- | -------- | ----------- |
| `options` | `{ timeout?: number }` | No       | —           |

**Returns** `string`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-input-value)

***

### boundingBox(options?)

Returns the bounding box of the element, or null if not visible.

<Note>
  Returns \{ x, y, width, height } in pixels relative to the main frame viewport.
  Scrolling affects the coordinates. Returns null if element is not visible.
</Note>

```ts
const box = await locator.boundingBox();
await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
```

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

**Returns** `PlaywrightBoundingBox \| null`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-bounding-box)

***

## State Checks

### isVisible(options?)

Returns whether the element is visible.

<Note>
  Does not wait for element to appear. For assertions, prefer expect(locator).toBeVisible().
</Note>

```ts
await runtime.page.locator(...).isVisible();
```

| Parameter | Type                   | Required | Description |
| --------- | ---------------------- | -------- | ----------- |
| `options` | `{ timeout?: number }` | No       | —           |

**Returns** `boolean`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-is-visible)

***

### isHidden(options?)

Returns whether the element is hidden.

<Note>
  Opposite of isVisible(). For assertions, prefer expect(locator).toBeHidden().
</Note>

```ts
await runtime.page.locator(...).isHidden();
```

| Parameter | Type                   | Required | Description |
| --------- | ---------------------- | -------- | ----------- |
| `options` | `{ timeout?: number }` | No       | —           |

**Returns** `boolean`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-is-hidden)

***

### isEnabled(options?)

Returns whether the element is enabled.

<Note>
  For assertions, prefer expect(locator).toBeEnabled().
</Note>

```ts
await runtime.page.locator(...).isEnabled();
```

| Parameter | Type                   | Required | Description |
| --------- | ---------------------- | -------- | ----------- |
| `options` | `{ timeout?: number }` | No       | —           |

**Returns** `boolean`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-is-enabled)

***

### isDisabled(options?)

Returns whether the element is disabled.

<Note>
  For assertions, prefer expect(locator).toBeDisabled().
</Note>

```ts
await runtime.page.locator(...).isDisabled();
```

| Parameter | Type                   | Required | Description |
| --------- | ---------------------- | -------- | ----------- |
| `options` | `{ timeout?: number }` | No       | —           |

**Returns** `boolean`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-is-disabled)

***

### isChecked(options?)

Returns whether a checkbox or radio is checked.

<Note>
  For assertions, prefer expect(locator).toBeChecked().
</Note>

```ts
await runtime.page.locator(...).isChecked();
```

| Parameter | Type                   | Required | Description |
| --------- | ---------------------- | -------- | ----------- |
| `options` | `{ timeout?: number }` | No       | —           |

**Returns** `boolean`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-is-checked)

***

### isEditable(options?)

Returns whether the element is editable.

<Note>
  For assertions, prefer expect(locator).toBeEditable().
</Note>

```ts
await runtime.page.locator(...).isEditable();
```

| Parameter | Type                   | Required | Description |
| --------- | ---------------------- | -------- | ----------- |
| `options` | `{ timeout?: number }` | No       | —           |

**Returns** `boolean`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-is-editable)

***

## Waiting

### waitFor(options?)

Waits for element to satisfy the given state.

<Note>
  State options: 'attached', 'detached', 'visible', 'hidden'.
  Returns immediately if condition is already met. Default state is 'visible'.
</Note>

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

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

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-wait-for)

***

## Screenshots & PDF

### screenshot(options?)

Takes a screenshot of the element.

<Note>
  Waits for actionability checks and scrolls element into view.
  Returns screenshot clipped to element size and position.
</Note>

```ts
await runtime.page.locator(...).screenshot();
```

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

**Returns** `Buffer`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-screenshot)

***

## Evaluation

### evaluate(pageFunction, arg?, options?)

Evaluates a function in the browser context with the element as first argument.

<Note>
  Returns the value of the evaluated function. The function receives the DOM element as first argument.
</Note>

```ts
const tagName = await locator.evaluate(el => el.tagName);
```

| Parameter      | Type                                                                   | Required | Description                             |
| -------------- | ---------------------------------------------------------------------- | -------- | --------------------------------------- |
| `pageFunction` | `string \| ((element: Element, arg: Arg) =&gt; R \| Promise&lt;R&gt;)` | Yes      | Function to evaluate in browser context |
| `arg`          | `Arg`                                                                  | No       | Argument to pass to function            |
| `options`      | `PlaywrightEvaluateOptions`                                            | No       | —                                       |

**Returns** `R`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-evaluate)

***

### evaluateAll(pageFunction, arg?)

Evaluates a function with all matching elements as first argument.

<Note>
  Does not wait for elements - returns empty array if none match.
</Note>

```ts
const count = await locator.evaluateAll(els => els.length);
```

| Parameter      | Type                                                                      | Required | Description                             |
| -------------- | ------------------------------------------------------------------------- | -------- | --------------------------------------- |
| `pageFunction` | `string \| ((elements: Element[], arg: Arg) =&gt; R \| Promise&lt;R&gt;)` | Yes      | Function to evaluate in browser context |
| `arg`          | `Arg`                                                                     | No       | Argument to pass to function            |

**Returns** `R`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-evaluate-all)

***

### evaluateHandle(pageFunction, arg?)

Returns a JSHandle with the result of the evaluation.

<Note>
  Use when you need to retain a reference to a JavaScript object in the page. Note: JSHandle is not fully supported in the remote SDK.
</Note>

```ts
await runtime.page.locator(...).evaluateHandle(/* pageFunction */);
```

| Parameter      | Type                                                                   | Required | Description                             |
| -------------- | ---------------------------------------------------------------------- | -------- | --------------------------------------- |
| `pageFunction` | `string \| ((element: Element, arg: Arg) =&gt; R \| Promise&lt;R&gt;)` | Yes      | Function to evaluate in browser context |
| `arg`          | `Arg`                                                                  | No       | Argument to pass to function            |

**Returns** `unknown`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-evaluate-handle)

***

## Other

### elementHandle(options?)

Resolves to the ElementHandle of the element.

<Note>
  Returns the handle to the element that matches this locator.
  Throws if no elements or multiple elements match.
</Note>

```ts
await runtime.page.locator(...).elementHandle();
```

| Parameter | Type                   | Required | Description |
| --------- | ---------------------- | -------- | ----------- |
| `options` | `{ timeout?: number }` | No       | —           |

**Returns** `RemotePlaywrightElementHandle`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-element-handle)

***

### elementHandles()

Resolves to all ElementHandles matching this locator.

<Note>
  Returns an empty array if no elements match.
</Note>

```ts
await runtime.page.locator(...).elementHandles();
```

**Returns** `RemotePlaywrightElementHandle[]`

[Upstream docs](https://playwright.dev/docs/api/class-locator#locator-element-handles)

***