A locator describes how to find elements. It is lazy: it is resolved again on every call, so it survives the page re-rendering. Matching uses Playwright’s own selector engine, run inside the page.
row = page.locator("tr").filter(has_text="invoice-42")
row.get_by_role("button", name="Delete").click()

How actions wait

Every action waits, inside the session, until its element is ready:
  1. Resolve. The locator must match exactly one element. If it matches none yet, the session keeps looking.
  2. Wait until actionable. The element is visible, stable (the same box on two checks in a row), enabled (for click, fill, check and select) and editable (for fill). An element partly outside the viewport is scrolled to the middle.
  3. Act with real operating-system input. The pointer goes to the element’s center, or to position.
Reads wait only until the element is attached. Timeouts are milliseconds: 5,000 by default, or the page’s set_default_timeout(), and at most 60,000. Running out raises TimeoutError naming the check that failed. Strictness. Actions and single-element reads fail when the locator matches more than one element: TimeoutError at once, with a message saying how many matched. Narrow it with first, last, nth() or filter(). count(), all(), all_inner_texts(), all_text_contents() and evaluate_all() work on every match.

Narrowing

locator.first, locator.last, locator.nth()

The first match, the last match, or the match at index (zero-based; -1 is the last).
locator.nth(index)
Returns Locator.

locator.filter()

Narrow the matches by text, by an element inside them, or by visibility.
locator.filter(*, has_text=None, has_not_text=None, has=None, has_not=None, visible=None)
ParameterTypeDefaultDescription
has_textstr | re.Pattern | NoneNoneKeep matches containing this text, case-insensitively.
has_not_textstr | re.Pattern | NoneNoneDrop matches containing it.
hasLocator | NoneNoneKeep matches that contain an element this locator finds.
has_notLocator | NoneNoneDrop matches that contain one. It must be a locator made from a selector string, such as page.locator(".badge").
visiblebool | NoneNoneKeep only visible (True) or only hidden (False) matches.
Returns Locator.

locator.locator() and locator.get_by_*()

Find elements inside this locator’s element. locator() takes a selector string or another Locator, plus the filter() keywords except visible; the get_by_* methods take what they take on Page.
dialog = page.get_by_role("dialog")
dialog.get_by_role("button", name="Save").click()
dialog.locator("input[name=email]").fill("ada@example.com")
locator.get_by_query() finds the element a description names inside this one, as page.get_by_query() does on the page.

locator.with_options()

This locator with its resolver picked, for every later call.
locator.with_options(*, strategy=None, model=None, ocr_engine=None)
strategy and model are as described in How a locator resolves. ocr_engine is "free" or "premium", for strategy="vision". With no arguments it returns the same locator.
total = page.get_by_text("Total").with_options(strategy="vision")

locator.and_() and locator.or_()

Elements that match both locators, or either.
page.get_by_role("button").and_(page.get_by_title("Subscribe"))
page.get_by_text("Accept").or_(page.get_by_text("Agree"))

locator.all()

One locator per current match, in document order. Doesn’t wait. Returns list[Locator].

Actions

locator.click()

locator.click(*, button=None, click_count=None, modifiers=None, position=None,
              force=False, trial=False, timeout=None)
ParameterTypeDefaultDescription
buttonstr | None"left""left", "right" or "middle".
click_countint | None12 for a double click.
modifierslist[str] | NoneNoneKeys held during the click: "Control", "Shift", "Alt".
positiondict | Nonecenter{"x", "y"} in CSS pixels from the element’s top-left.
forceboolFalseSkip every actionability check except having a box.
trialboolFalseRun the checks without clicking.
timeoutfloat | None5000Milliseconds.

locator.dblclick(), locator.tap()

dblclick(**options) is click(click_count=2, **options). tap(**options) is click(**options): browser sessions take mouse input.

locator.hover()

locator.hover(*, position=None, force=False, trial=False, timeout=None)

locator.fill() and locator.clear()

Focus the element, select everything in it, delete it, and type value. clear() is fill("").
locator.fill(value, *, force=False, timeout=None)
locator.clear(*, force=False, timeout=None)

locator.press_sequentially()

Focus the element, then type text one key at a time without clearing it. locator.type() is the same.
locator.press_sequentially(text, *, delay=None, timeout=None)
ParameterTypeDefaultDescription
delayfloat | NoneNoneMilliseconds between keys.

locator.press()

Focus the element and press a key or chord, such as "Enter" or "Control+a". See Keyboard for key names.
locator.press(key, *, timeout=None)

locator.check(), locator.uncheck(), locator.set_checked()

Click only when the state differs, then confirm it changed.
locator.check(*, force=False, timeout=None)
locator.uncheck(*, force=False, timeout=None)
locator.set_checked(checked, *, force=False, timeout=None)

locator.select_option()

Select options of a <select> by value or visible label, and fire input and change.
locator.select_option(value=None, *, label=None, timeout=None)
ParameterTypeDefaultDescription
valuestr | list[str] | NoneNoneOption values.
labelstr | list[str] | NoneNoneOption labels.
Returns list[str]: the values now selected.

locator.focus(), locator.blur(), locator.scroll_into_view_if_needed()

Focus or blur the element by script, or scroll it into view.
locator.focus(*, timeout=None)
locator.blur(*, timeout=None)
locator.scroll_into_view_if_needed(*, timeout=None)

locator.drag_to()

Press on this element, move to target, and release there, with the real mouse.
locator.drag_to(target, *, source_position=None, target_position=None,
                force=False, trial=False, timeout=None)
ParameterTypeDefaultDescription
targetLocatorrequiredWhere to drop.
source_position, target_positiondict | Nonecenters{"x", "y"} from each element’s top-left.

locator.dispatch_event()

Dispatch a DOM event on the element by script. It is not real input, so it is not a click.
locator.dispatch_event(type, event_init=None, *, timeout=None)

locator.set_input_files()

Choose files for an <input type="file">, as Playwright does.
locator.set_input_files(files, *, timeout=None)
ParameterTypeDefaultDescription
filesstr | Path | dict | listrequiredA local path, a payload {"name", "mimeType", "buffer"} with buffer as bytes, or a list of either. [] clears the input.
timeoutfloat | None5000Milliseconds to wait for the input.
The browser runs in its own machine, so each file is copied there first and then set on the input. The page sees the file under its own name (a path’s file name, or the payload’s name). Characters Windows doesn’t allow in a file name become _. A second file with the same name in one call is renamed, such as notes (2).txt. Each file can be up to 32 MiB. A hidden input works, as in Playwright.
page.get_by_label("Resume").set_input_files("cv.pdf")
page.locator("input[type=file]").set_input_files([
    "photo.jpg",
    {"name": "notes.txt", "mimeType": "text/plain", "buffer": b"hello"},
])
page.locator("input[type=file]").set_input_files([])   # clear it
Raises ValueError for a payload without name or buffer; TypeError for anything else that isn’t a path or a payload; OSError when a local path can’t be read. page.set_input_files(selector, files) is the same on page.locator(selector).

locator.screenshot()

Not available yet. Raises UnsupportedError. For a picture of an element, use page.screenshot() with locator.bounding_box().

Reads

locator.inner_text(), text_content(), inner_html(), input_value()

locator.inner_text(*, timeout=None)     # -> str
locator.text_content(*, timeout=None)   # -> str | None
locator.inner_html(*, timeout=None)     # -> str
locator.input_value(*, timeout=None)    # -> str
input_value reads an <input>, <textarea> or <select>.

locator.get_attribute()

locator.get_attribute(name, *, timeout=None)
Returns str | None: None when the attribute is absent.

locator.all_inner_texts() and locator.all_text_contents()

Every match’s text, in document order. Doesn’t wait. Returns list[str].

locator.count()

How many elements match now. Doesn’t wait. Returns int.

locator.bounding_box()

locator.bounding_box(*, timeout=None)
Returns {"x", "y", "width", "height"} in the page’s CSS pixels from the viewport’s top-left, or None when the element isn’t rendered.

locator.aria_snapshot()

The element’s accessibility tree as Playwright’s YAML aria snapshot. See page.aria_snapshot(). Returns str.

States

locator.is_visible() and locator.is_hidden()

Whether the element is visible (or hidden) now. They don’t wait: no match counts as hidden. Returns bool.

locator.is_enabled(), is_disabled(), is_editable(), is_checked(), is_focused()

Wait until the element is attached, then answer.
locator.is_enabled(*, timeout=None)
Returns bool. Raises UnsupportedError from is_checked() when the element isn’t a checkbox or radio button.

locator.wait_for()

Wait until the locator is "attached", "detached", "visible" or "hidden".
locator.wait_for(*, state="visible", timeout=None)

Scripts

locator.evaluate()

Run expression with the element as its first argument and arg as its second.
locator.evaluate(expression, arg=..., *, world=None, timeout=None)
It runs in the isolated world unless world="main"; see page.evaluate().
href = page.get_by_role("link", name="Docs").evaluate("el => el.href")
Returns the result as Python values. Raises EvaluationError when the script throws.

locator.evaluate_all()

Run expression once, with a list of every match as its first argument and arg as its second, and return its result, as Playwright does. It doesn’t wait for matches: with none, the list is empty.
locator.evaluate_all(expression, arg=..., *, world=None)
ParameterTypeDefaultDescription
expressionstrrequiredA function that takes the list of elements.
argAnynoneOne JSON value passed as the second argument.
worldstr | None"isolated""isolated" or "main"; see page.evaluate().
texts = page.locator("li").evaluate_all("els => els.map(e => e.textContent)")
count = page.locator("li").evaluate_all("(els, min) => els.filter(e => e.children.length >= min).length", 2)
Returns the result as Python values. Raises EvaluationError when the script throws.

locator.highlight()

Accepted for compatibility; does nothing.