Selectors

A selector is a pattern that tells RTILA X which element (or elements) on a web page to interact with or extract data from. Think of a selector as an address — it points to a specific location on the page so RTILA knows exactly where to look.

Every command that interacts with an element (click, fill, extract) and every dataset property uses selectors. Understanding selectors is the single most important skill for building reliable automations.

RTILA X supports 4 selector types, each designed for a different situation. You can even combine them for maximum reliability.

Selector Format

All selectors in RTILA X follow this format:

type=value

The type tells RTILA how to interpret the value. For example:

Format	Meaning
css=.product-card	Find elements using CSS selector .product-card
xpath=//div[@class='item']	Find elements using XPath expression
text=Add to Cart	Find elements containing exact text “Add to Cart”
variable=my_var	Use the value of runtime variable my_var as the selector

You can also combine multiple selectors separated by commas. RTILA will try each one in order and use the first that matches:

css=.product-card,xpath=//div[@class='item'],text="Product Card"

This “fallback chain” approach makes your automations more resilient — if one selector breaks due to a website update, the next one may still work.

CSS Selectors

CSS selectors are the most common and versatile selector type. They use standard CSS syntax that web developers use to style pages. If you’ve ever seen HTML or CSS, you’ll recognize this syntax immediately.

CSS Selector Syntax Reference

Pattern	Matches	Example
css=.classname	Elements with a specific class	css=.product-card
css=#idname	Element with a specific ID	css=#main-content
css=tagname	All elements of a specific HTML tag	css=div, css=a, css=h1
css=tag.class	Tag with a specific class	css=div.product-card
css=tag#id	Tag with a specific ID	css=div#header
css=[attribute]	Elements with a specific attribute	css=[data-product-id]
css=[attribute="value"]	Elements with an attribute value	css=[data-id="123"]
css=parent > child	Direct child elements	css=ul > li
css=ancestor descendant	Any descendant elements	css=div.product span.price
css=element:nth-of-type(n)	Nth element of its type	css=div:nth-of-type(2)
css=element:first-child	First child element	css=li:first-child
css=element:last-child	Last child element	css=li:last-child
css=[attribute^="start"]	Attribute starts with value	css=[href^="https"]
css=[attribute$="end"]	Attribute ends with value	css=[src$=".jpg"]
css=[attribute*="contains"]	Attribute contains value	css=[class*="product"]

CSS Selector Examples

Here are practical examples you’ll encounter in real scraping projects:

Selector	What It Finds	Use Case
css=.product-card	All elements with class “product-card”	Selecting product cards on a listing page
css=#search-input	Element with ID “search-input”	Filling a search box
css=a[href^="/products"]	Links starting with “/products”	Finding product links
css=img[src$=".jpg"]	Images ending in “.jpg”	Finding product images
css=.product-card h2	H2 tags inside product cards	Extracting product titles
css=.product-card .price	Price elements inside product cards	Extracting prices
css=button.add-to-cart	Buttons with class “add-to-cart”	Clicking “Add to Cart” buttons
css=input[name="email"]	Input with name attribute “email”	Filling email fields
css=div:nth-of-type(3)	Third div sibling	Selecting a specific position
css=[data-product-id="SKU123"]	Element with specific data attribute	Finding a specific product
css=.pagination a.next	Next page link in pagination	Navigating to next page
css=table tr > td:first-child	First cell in each table row	Extracting first column data

How CSS Selectors Are Generated

When you use the Element Picker (the pointer icon in the Visual Builder), RTILA automatically generates CSS selectors using a priority system. It tries the most stable approaches first:

Priority	Strategy	Example	Why It’s Stable
1	data-* attributes	[data-product-id="12345"]	Custom attributes rarely change
2	aria-label attribute	[aria-label="Add to Cart"]	Accessibility labels are intentional
3	role attribute	[role="button"]	ARIA roles are semantic
4	name attribute	[name="email"]	Form names are functional
5	id (if stable)	#main-content	IDs are unique identifiers
6	title attribute	[title="View Details"]	Titles describe purpose
7	alt attribute	[alt="Product Image"]	Alt text describes images
8	placeholder attribute	[placeholder="Enter email"]	Placeholders guide users
9	Safe CSS classes	.product-card	Meaningful class names
10	Position (:nth-of-type)	div:nth-of-type(2)	Last resort for unique elements

RTILA walks up the DOM tree from your selected element, building a selector path until it finds one that uniquely identifies the element on the page.

XPath Selectors

XPath (XML Path Language) is a powerful query language for navigating HTML documents. It can express complex conditions that CSS selectors cannot handle.

XPath Selector Syntax Reference

Pattern	Matches	Example
xpath=//tag	All elements of a tag anywhere	xpath=//div
xpath=//tag[@attr='value']	Elements with attribute value	xpath=//div[@class='item']
xpath=//tag[contains(text(),'text')]	Elements containing text	xpath=//button[contains(text(),'Submit')]
xpath=//tag[@attr='val']/child	Child of matching parent	xpath=//div[@id='main']/p
xpath=//tag[position()]	Element at position	xpath=//li[1]
xpath=//tag[last()]	Last matching element	xpath=//li[last()]
xpath=//tag[@attr and @attr2]	Elements with multiple attributes	xpath=//input[@type='text' and @name='q']

XPath Selector Examples

Selector	What It Finds	Use Case
xpath=//div[@class='product-card']	Divs with class “product-card”	Same as CSS but XPath syntax
xpath=//a[contains(text(),'Next')]	Links containing “Next” text	Finding “Next Page” links
xpath=//button[@type='submit']	Submit buttons	Finding form submit buttons
xpath=//div[@id='results']//a	All links inside div#results	Finding links in a specific container
xpath=//table//tr[position()>1]	Table rows except the first	Skipping header rows
xpath=//input[@placeholder='Search...']	Input with specific placeholder	Finding search fields
xpath=//span[contains(@class,'price')]	Spans with “price” in class	Finding price elements
xpath=//div[@data-id and @data-name]	Divs with both data attributes	Finding elements with multiple attributes

When to Use XPath Over CSS

Scenario	Use XPath	Use CSS
Select by text content	✅ contains(text(),'...')	❌ Not possible
Select parent from child	✅ .. (parent axis)	❌ Not possible
Complex attribute conditions	✅ Multiple and/or conditions	⚠️ Limited
Simple class/ID selection	⚠️ Works but verbose	✅ Simpler syntax
Position-based selection	✅ [position()], [last()]	⚠️ Limited
Attribute starts/ends with	⚠️ Uses starts-with()	✅ ^=, $= operators

Rule of thumb: Use CSS selectors for simple selections. Use XPath when you need text matching, parent traversal, or complex conditions.

Text Selectors

Text selectors find elements by their exact visible text content. This is useful when you know the exact text of a button or link but don’t know its CSS class or structure.

Text Selector Syntax

text=Exact Text Here

How Text Selectors Work

• The text must match exactly (case-sensitive).
• The text is matched against the element’s visible text content.
• Partial matches are not supported. text=Add will NOT match “Add to Cart”.
• The text is trimmed of leading/trailing whitespace before matching.

Text Selector Examples

Selector	What It Finds	Use Case
text=Add to Cart	Button/link with text “Add to Cart”	Clicking a specific button
text=Sign In	Element with text “Sign In”	Finding login button
text=Next Page	Element with text “Next Page”	Navigating pagination
text=Submit Order	Element with text “Submit Order”	Submitting a form

When to Use Text Selectors

Scenario	Recommended?	Why
Button with known text	✅ Yes	Simple and readable
Multilingual websites	❌ No	Text changes by language
Dynamic text (prices, counts)	❌ No	Text changes frequently
Navigation links	✅ Yes	Usually stable text
Headings	✅ Yes	Headings rarely change

Warning: Text selectors break if the website changes its wording. If a button says “Add to Cart” today but “Add to Bag” tomorrow, your selector will fail. Prefer CSS or XPath selectors when possible.

Variable Selectors

Variable selectors use the value of a runtime variable as the selector. This allows you to build dynamic selectors that change based on data extracted earlier in your automation.

Variable Selector Syntax

variable=variable_name

How Variable Selectors Work

1. During execution, RTILA looks up the runtime variable by name.
2. The variable’s value is used as a CSS selector.
3. The element matching that selector is used for the operation.

Variable Selector Examples

Selector	What It Does	Use Case
variable=dynamic_selector	Uses the value stored in dynamic_selector variable	Dynamic element targeting
variable=extracted_xpath	Uses an XPath stored in a variable	Using extracted selectors

When to Use Variable Selectors

Scenario	Recommended?	Why
Selector determined at runtime	✅ Yes	Dynamic targeting
Selector extracted from page	✅ Yes	Using page-provided selectors
Static element selection	❌ No	Use CSS/XPath directly
Simple known elements	❌ No	Overkill for static targets

Tip: Variable selectors are advanced. Most automations don’t need them. Use CSS or XPath selectors for static elements and only use variable selectors when the selector itself is determined during execution.

Choosing the Right Selector

Use this decision table to pick the best selector type for your situation:

Scenario	Best Selector	Example
Element has a unique ID	CSS (#id)	css=#login-form
Element has a stable class	CSS (.class)	css=.product-card
Element has a data attribute	CSS ([data-*])	css=[data-product-id="123"]
Element has an aria-label	CSS ([aria-label])	css=[aria-label="Close"]
Need to match by text	XPath (contains(text(),...))	xpath=//button[contains(text(),'Submit')]
Need parent/ancestor traversal	XPath (.., ancestor::)	xpath=//span/ancestor::div[@class='card']
Simple button with known text	Text selector	text=Add to Cart
Selector determined at runtime	Variable selector	variable=my_selector
Complex nested structure	XPath	xpath=//div[@id='main']//span[@class='price']
First/last element in a list	XPath ([1], [last()])	xpath=//li[1]
Element by attribute value	CSS ([attr="value"])	css=[type="submit"]
Element by attribute contains	CSS ([attr*="value"])	css=[class*="product"]

Selector Tips

Tip	Why It Matters
Prefer IDs and data attributes	They’re the most stable and least likely to change
Use the Element Picker	More reliable than typing selectors manually
Test on multiple pages	Verify selectors work across different pages of the same site
Avoid auto-generated classes	Classes like css-1a2b3c or sc-xyz change frequently
Use fallback chains	Combine selectors: css=.primary,xpath=//div[@class='backup']
Avoid nth-child when possible	Position-based selectors break when content changes
Use specific selectors	css=.product-card h2 is better than css=h2
Prefer semantic attributes	aria-label, role, data-* are intentional and stable
Test after website updates	Websites change. Re-test selectors periodically.
Use text selectors sparingly	They break when wording changes

Iframe Selectors

Some web pages contain iframes — embedded pages within a page. If the element you need is inside an iframe, you must specify the iframe selector separately.

How Iframe Selectors Work

In RTILA X, iframe selectors are specified in the iframe parameter of commands, not in the main selector:

{
  "command": "click",
  "params": {
    "selector": "css=.submit-button",
    "iframe": "css=iframe#content-frame"
  }
}

Iframe Selector Rules

Rule	Description
Use CSS selectors for iframes	The iframe parameter only accepts CSS selectors
Specify the iframe element	Target the <iframe> tag itself, not content inside it
Chain nested iframes	For nested iframes, specify each iframe level
Same-origin only	Cross-origin iframes may not be accessible

Iframe Selector Examples

Iframe Selector	What It Targets
css=iframe#main-frame	Iframe with ID “main-frame”
css=iframe[name="content"]	Iframe with name “content”
css=iframe[src*="payment"]	Iframe whose src contains “payment”
css=.modal iframe	Iframe inside a modal container

Finding Iframe Selectors

1. Open the page in your browser.
2. Right-click the element inside the iframe.
3. Select “Inspect” to open developer tools.
4. Look for the <iframe> tag in the DOM tree.
5. Note the iframe’s id, name, or src attribute.
6. Use that as your iframe selector: css=iframe#the-id

Note: The Element Picker in the Visual Builder works within the main page context. For elements inside iframes, you may need to type the iframe selector manually.

Element Picker Integration

The Element Picker is a visual tool in the Visual Builder that generates selectors for you. Instead of typing CSS or XPath manually, you simply click on elements on the page.

How the Element Picker Works

1. Click the pointer icon (🖱️) next to any selector input field.
2. Your cursor changes to a crosshair.
3. Move your mouse over the page — elements are highlighted with a red overlay.
4. Click the element you want to select.
5. The refinement panel appears with green highlights on all matching elements.
6. Click ✓ to confirm, or ✗ to exclude specific elements.
7. The generated selector is inserted into the input field.

Selector Generation Priority

The Element Picker generates selectors using this priority:

1. Stable attributes — data-*, aria-label, role, name, title, alt, placeholder
2. ID — If the element has a stable, non-dynamic ID
3. Safe CSS classes — Classes that pass the dynamic class filter
4. XPath fallback — For complex nested structures
5. Text matching — As a last resort for text-based elements

Multi-Strategy Selector Output

The Element Picker generates a comma-separated selector with multiple strategies:

css=div.product-card[data-id="123"],xpath=//div[@data-id="123"],text="Product Name"

RTILA tries each strategy in order during execution, using the first one that successfully finds the element.

Dynamic Class Avoidance

RTILA X includes intelligent logic to detect and avoid dynamic CSS classes — classes that are auto-generated by frameworks and change frequently. Using these classes in selectors would cause your automations to break every time the website rebuilds.

What Gets Filtered

The isDynamic function identifies and skips these patterns:

Pattern	Example	Why It’s Dynamic
Pure numbers	12345	Generated IDs that change per build
Random alphanumeric (7+ chars)	aB3kF9x2	Hash-based class names
UUIDs	f47ac10b-58cc-4372-a567-0e02b2c3d479	Unique identifiers per session
Long hex strings (10+ chars)	a1b2c3d4e5f6	Build-time hashes
Strings with 4+ consecutive digits	item12345	Dynamic counters
Very short strings (≤2 chars)	ab	Too generic to be meaningful
No vowels (4+ chars)	xyzq	Likely auto-generated

Safe Classes Filter

The getSafeClasses function filters an element’s classes to only include stable ones:

Filter	What Gets Removed	Example
Dynamic patterns	Classes matching isDynamic()	css-1a2b3c, sc-xyz
CSS-in-JS prefixes	Classes starting with css-	css-1a2b3c
styled-components	Classes starting with sc-	sc-bdVaJa
Tailwind CSS	Classes starting with tw-	tw-flex
React internal	Classes starting with r-	r-1h0z55a
Material UI	Classes starting with Mui	MuiButton-root
Short classes	Classes with ≤2 characters	ab, x

Classes that pass all these filters are considered “safe” and are used in generated selectors.

What This Means for You

When you use the Element Picker:

• RTILA automatically avoids unstable classes.
• Generated selectors use the most stable attributes available.
• You don’t need to worry about framework-specific class names.
• Your selectors are more likely to survive website updates.

If you type selectors manually, try to follow the same principles:

• Prefer data-* attributes, aria-label, role, id, name
• Avoid classes that look like random strings
• Avoid classes starting with css-, sc-, tw-, r-, Mui
• Use meaningful class names like .product-card, .nav-menu, .price-tag

Stable Attributes Priority

When RTILA generates selectors (either via the Element Picker or internally), it checks for stable attributes in this order:

Priority	Attribute	Example Selector	Stability
1	data-* attributes	[data-product-id="12345"]	⭐⭐⭐⭐⭐ Highest
2	aria-label	[aria-label="Add to Cart"]	⭐⭐⭐⭐⭐ Very High
3	role	[role="button"]	⭐⭐⭐⭐ High
4	name	[name="email"]	⭐⭐⭐⭐ High
5	id (stable)	#main-content	⭐⭐⭐⭐ High (if not dynamic)
6	title	[title="View Details"]	⭐⭐⭐ Medium
7	alt	[alt="Product Image"]	⭐⭐⭐ Medium
8	placeholder	[placeholder="Enter email"]	⭐⭐⭐ Medium
9	Safe CSS classes	.product-card	⭐⭐ Medium
10	Position (:nth-of-type)	div:nth-of-type(2)	⭐ Low (last resort)

Key insight: The higher the priority, the more likely the selector will survive website updates. Always prefer data attributes and ARIA attributes over class names or positions.

Selector Debugging

If a selector isn’t working:

Problem	Solution
Selector finds wrong element	Make the selector more specific. Add parent context or attributes.
Selector finds no elements	Check for typos. Verify the element exists on the page. Try a different selector type.
Selector works on one page but not another	The element structure may differ. Use a more generic selector or add fallbacks.
Selector broke after website update	The website changed. Use the Element Picker to regenerate the selector.
Selector is too slow	Simplify the selector. Avoid deeply nested XPath expressions.

Testing Selectors in the Browser

You can test CSS selectors directly in your browser’s developer console:

1. Open the page in your browser.
2. Press F12 to open developer tools.
3. Switch to the Console tab.
4. Type: document.querySelectorAll('YOUR_SELECTOR')
5. Press Enter.
6. If elements are returned, your selector works. If the list is empty, it doesn’t match anything.

For XPath selectors:

document.evaluate('//YOUR_XPATH', document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null).snapshotLength

This returns the number of matching elements. If it returns 0, your XPath doesn’t match anything.