Skip to content

Playwright CSS Selectors: Locate Elements and Read Their Text

Playwright's locator() method accepts a CSS selector and returns a locator that points at the matching element.

OUTPUT FORMATSHTMLJSONMarkdown

You can pass the selector directly and let Playwright infer its type, or add the css= prefix so the engine treats it unambiguously as CSS. This guide shows the syntax, walks through a small Python example that prints a page title, and explains what to check when a selector does not behave as expected.

How Playwright resolves a CSS selector

Call locator() on a Page object and give it a CSS selector string. Playwright inspects the string and recognizes CSS automatically, so page.locator('title') and page.locator('css=title') both target the document title element. The explicit css= form is useful when a selector could be mistaken for another selector language or when you want the intent visible in code. The locator itself is lazy: it describes which element to find, and the lookup happens when you perform an action or read a value such as text_content().

A minimal Python example

The workflow has five steps: start Playwright, launch a browser, open a new page, navigate to a URL, and read text from a located element. The sample below uses Chromium with a visible window, goes to a site, locates the title element with the css= prefix, and prints its text content. Replace the base URL placeholder with the page you are allowed to inspect. The full exact script is supplied in the accompanying protected code module and should be used as the authoritative version.

Selector decision checklist

Before running a script, confirm the following:

  • The selector matches the element you intend, not a wrapper or a duplicate.
  • You know whether the page renders the target before or after JavaScript runs.
  • You have chosen between a bare selector and the css= prefix deliberately.
  • The element exposes text through text_content() if that is what you plan to read.
  • The URL you navigate to is one you are permitted to access.

Two different failure shapes

A CSS lookup can fail in two distinct ways, and the fix differs. If nothing matches, the locator has no element to act on; check the selector spelling, the page state, and whether the content is loaded. If several elements match, the locator is ambiguous and an action that expects one target may raise an error; narrow the selector with an id, a class, or a structural relationship. Treating both cases as the same problem often leads to unnecessary waits when the real issue is an over-broad selector.

Field and control map for the sample

The script's moving parts map cleanly to Playwright concepts:

  • sync_playwright() opens the context manager that owns the browser session.
  • p.chromium.launch(headless=False) starts a visible Chromium instance.
  • browser.new_page() creates the page object that exposes locator().
  • page.goto(url) navigates to the target document.
  • page.locator('css=title') builds the CSS-based locator.
  • title.text_content() returns the element's text for printing.

Related Playwright tasks

Once CSS selection is working, nearby tasks often follow: waiting for a page to finish loading, blocking unnecessary resources, capturing background requests and responses, downloading files, switching to XPath selectors, loading local files, running Playwright inside Jupyter notebooks, saving and loading cookies, and taking screenshots. Each of these has its own dedicated question page in the Playwright web scraping series.

Frequently asked questions

Do I need the css= prefix for every selector?

No. Playwright can detect that a CSS selector is being passed in as an argument. The prefix is optional and mainly removes ambiguity about which selector language you intend.

What object provides the locator method?

The Page object. You call locator() on a page instance, then use the returned locator to read text or perform other actions.

How do I print the text of a located element?

Call text_content() on the locator and pass the result to print(). The sample script locates the title element and prints its text content.

Why does my selector sometimes match more than one element?

CSS selectors can describe broad groups, such as every element with a given class. If an action expects a single target, narrow the selector so it identifies one element.