CSS selectors

Selector syntax

Web Scraper accepts browser-supported CSS selectors and additional selector syntax provided by Web Scraper. Enter the selector in the selector configuration and use Element Preview to verify the match.

Prefer stable selectors

Prefer descriptive IDs, classes and data attributes that remain consistent between records.
Avoid long generated class names when a simpler structural selector is available.
Prefer selectors based on stable attributes, classes or structure rather than an element's position on the page.
Test the selector on more than one category or detail page.

Target multiple CSS selectors

When creating a selector manually, use a comma to target more than one CSS selector:

.price, .original-price

This matches elements that satisfy either CSS selector. The order of the CSS selectors in the input does not define which matched element is returned first.

How matched elements are returned

Matched elements are processed in document order. This means Web Scraper follows the order in which matching elements appear in the page HTML, not the order in which CSS selectors are written in the selector input.

For example, with .price, .original-price:

If an element matching .price appears first in the HTML, it is returned first.
If an element matching .original-price appears first in the HTML, it is returned first.

This behavior is the same when more than two CSS selectors are combined in a single selector.

Multiple matches and returned values

A CSS selector can match more than one element. Web Scraper uses two different controls for handling multiple matches, depending on the selector type. A selector uses either a Multiple checkbox or a Multiple type dropdown.

Selectors with a Multiple checkbox

HTML, Link, Table, Element and Element Click selectors use a Multiple checkbox.

Multiple disabled: only the first matching element in HTML document order is used.
Multiple enabled: all matching elements are processed. When the selector creates records, each matched element can create its own output record.

Selectors with a Multiple type dropdown

Text, Image and Element Attribute selectors do not use a Multiple checkbox. They use a Multiple type dropdown that defines how several matches are returned.

First Record Only: returns the first matching element in HTML document order.
Multiple Records in Multiple Columns: returns several matched values across the configured output columns.
Multiple Records in One Column: returns several matched values in one output column.

For every selector type, matched elements are evaluated in HTML document order. The order of comma-separated CSS expressions in the selector input does not change which matched element is considered first.

Select within a parent element

Child selectors run within their parent context. A simple selector such as .price can therefore be used beneath an Element selector that already limits the context to one product card.

Select the parent element

Use _parent_ from a child selector when the value must be extracted from the element returned by the parent Element selector.

Select content inside an iframe

iframe:iframe .selector-within-iframe

The first part selects the iframe. The :iframe boundary enters its document, and the remaining selector targets content inside it. Cross-origin and site-specific restrictions can still prevent access.

Select content inside a shadow root

.shadow-host:shadow-root .selector-within-shadow-root

The first selector identifies the shadow host. The :shadow-root boundary enters the shadow root.

Troubleshooting

Use Element Preview to determine whether the selector matches zero, one or multiple elements.
Inspect whether the target element appears only after a click, delay or scroll action.
Confirm that the selector is evaluated beneath the correct parent.
Check whether the website changes classes between page loads.