Cheerio: Find HTML Elements by Attribute Value
Attribute selection in Cheerio is really a question of intent: do you want elements that carry an attribute at all, elements whose attribute equals one specific string, or elements that lack the attribute entirely?
Each intent maps to a different selector shape, and mixing them up is the most common reason a scrape returns too many or too few nodes. This guide separates the three cases, walks through the supplied reference example, and gives you a checklist and failure test you can apply before you touch the HTML.
Three intents, three selector shapes
The attribute selector is not one pattern but a family, and the bracket contents decide which family member you get. If your goal is to confirm an attribute exists — say, any element flagged with a tracking key regardless of its value — the bare form [attr] is correct and will match broadly. If your goal is to isolate one record, the equality form [attr="value"] narrows the match to a single string and is the form the reference example uses. If your goal is the inverse — everything that does *not* carry the attribute — you invert with :not([attr]) rather than trying to express absence inside the brackets. Choosing the wrong shape is a semantic error, not a syntax error: the selector still runs, it just answers a different question than the one you asked. Decide which of the three intents you have before writing brackets, and the rest of the selector follows mechanically.
Worked example: matching one data attribute value
The supplied sample markup contains three divs. Two carry a data-example attribute with values 1 and 2; the third has no such attribute. The selector div[data-example="1"] matches only the first div, because equality is exact — the div with value 2 fails the comparison and the attribute-less div never enters the candidate set. The reference example (module code0001) loads the HTML, runs that selector, iterates the matches with .each, and prints each match's text. Treat it as the supplied illustrative example of the workflow rather than a runtime-verified script: it shows the shape of the call, not a tested execution against a live page.
Decision checklist before you run the selector
Use this short list to confirm your selector expresses the intent you actually have:
- Exact value:
[attr="value"]matches only elements whose attribute equals that string. - Presence only:
[attr]matches any element that has the attribute, regardless of value. - Negation:
:not([attr])excludes elements that carry the attribute. - Tag scoping: prefixing a tag name (
div[...]) narrows matches to that element type. - Quoting: keep the value inside quotes when it contains spaces or special characters.
- Iteration: use
.eachto walk every match; a single.text()call on the collection returns combined text, which may not be what you want per element.
Selector field map
Break any attribute selector into four parts and check each one:
- Tag — the element type to restrict to, e.g.
div. Omit it to match any tag. - Attribute name — the exact attribute key, e.g.
data-example. Case matters in HTML attribute names as written. - Operator —
=for exact equality. Other operators exist in CSS but are outside the scope of this example. - Value — the string to compare against, quoted inside the brackets.
If a selector returns nothing, walk these four parts in order before changing the HTML.
No match vs. matched but empty
Two different failures look similar in output. No match means the selector found zero elements; .each never runs. Matched but empty means the element exists but its text content is blank, so .each runs and prints an empty line. To tell them apart, log the collection length before iterating. If the length is zero, the selector is wrong or the attribute value differs. If the length is greater than zero but the text is empty, the element is present and the content is elsewhere — perhaps in a child node or an attribute rather than the text.
Frequently asked questions
What is the difference between [attr] and [attr="value"] in Cheerio?
[attr] matches any element that has the attribute, whatever its value. [attr="value"] matches only elements whose attribute equals that exact string. Use the first when you only care that the attribute exists; use the second when the value identifies the element you want.
Why does my Cheerio attribute selector return nothing?
Check four things in order: the tag name, the attribute name spelling and case, the operator, and the quoted value. Also confirm the HTML was loaded before the selector ran. Logging the collection length distinguishes a zero-match selector from a match with empty text.
How do I handle multiple elements that share the same attribute value?
The selector returns a collection. Use .each to iterate and read each element's text individually. Calling .text() once on the whole collection concatenates the text of every match, which is usually not what you want when you need per-element values.