Skip to content

Selecting HTML Elements by Text: CSS Limits and Working Alternatives

If you have tried to write a CSS selector that targets an element because of the words inside it, you have hit a real gap in the standard.

OUTPUT FORMATSHTMLJSONMarkdown

CSS selectors match structure, attributes and position, not the text content of a node. This guide explains why the old approach no longer works and shows two practical replacements: XPath in Selenium and a text filter in BeautifulSoup.

Why a CSS text selector is not the answer

:contains(text) was once used to pick elements by their text, but it has been deprecated for a long time and the W3C standard does not support it. Browsers and libraries that follow the standard will not treat it as a valid selector. If your goal is to find an element by the words it displays, you need a different mechanism rather than a CSS tweak. Most Python libraries offer one.

Option 1: XPath in Selenium

Selenium can locate an element by text through an XPath expression. The example below opens a page, then finds the first h1 whose text contains the word "Tired". The XPath function contains(text(), 'Tired') does the text matching that CSS cannot.

Option 2: BeautifulSoup text filter

BeautifulSoup takes a different route: you pass a compiled regular expression as the text argument to find. The snippet below fetches the page, parses it, and returns the h1 whose text matches "Tired". The printed result shows the matched tag together with its class attribute.

Choosing between the two

Use XPath when you are already driving a browser with Selenium and need to interact with the element. Use BeautifulSoup when you only need to parse returned HTML and extract values. Both approaches match on text content, so both inherit the same caveats: matching is on the text as rendered in the parsed document, and partial matches can catch more than one node.

Before you switch: a short checklist

  1. Confirm the element is identified by its text and not by a stable class or id; if a class exists, a normal CSS selector is simpler. 2. Decide whether you need a partial match (contains) or an exact match. 3. Check how many nodes match; take the first only if that is what you intend. 4. Remember that text inside child elements may not be part of the parent's direct text node. 5. Keep the selector close to the page structure so a layout change does not silently break it.
Text-matching approaches compared
ApproachWhere it runsText matchingBest for
CSS selector:contains(text)Deprecated, not in W3C standardNot usable for text matching
XPath in SeleniumBrowser automationcontains(text(), 'Tired')Interacting with a located element
BeautifulSoup text filterPython HTML parsingre.compile("Tired") passed as textExtracting values from returned HTML

The XPath and BeautifulSoup examples were captured as reference snippets; verify current library behavior before relying on them in production.

Frequently asked questions

Can I select an element by text with a plain CSS selector?

No. CSS selectors match structure, attributes and position. The :contains(text) pseudo-class that once allowed text matching is deprecated and not part of the W3C standard, so you should use XPath or a library text filter instead.

Does the XPath example match exact text or partial text?

It uses contains(text(), 'Tired'), which is a partial match: any h1 whose text includes the word "Tired" qualifies. If you need an exact match, use an equality comparison instead.

Why does BeautifulSoup use a regular expression for text?

The text argument accepts a compiled pattern, so re.compile("Tired") lets you match any element whose text contains that word. A plain string would require an exact match.

What if more than one element contains the text?

Both approaches return the first match by default. If several elements could match, narrow the selector with a tag name or attribute, or collect all matches and inspect them.