Element Picker

The Element Picker is the visual tool that lets you select elements on a web page by simply pointing and clicking. Instead of writing CSS selectors manually, you click the pointer icon, hover over the page, and click the element you want. RTILA generates a robust selector automatically.

The element picker is available in two places:

• Data Extraction tab: Next to the selector input for the item selector and each property.
• Web Automation tab: Next to selector parameters in command configurations.
• Dataset Settings modal: Next to the item container selector field.

---

How to Use the Element Picker

Step-by-Step

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 as you hover.
4. Click the element you want to select.
5. The refinement panel appears, showing green highlights on all matching elements.
6. Review the highlights:
   • Click ✓ to confirm the selector for all highlighted elements.
   • Click ✗ to exclude specific elements and refine the selection.
7. The generated selector is inserted into the input field.

Starting the Picker

The element picker can be started from:

• The pointer icon button next to any selector input.
• The picker activates for the specific input field you clicked.
• While active, the input field shows “Picking element…” as its placeholder.

Stopping the Picker

The picker stops when:

• You confirm or reject a selection.
• You click the pointer icon again (toggle off).
• You close the Visual Builder.
• You navigate away from the page.

---

Red Overlay Highlight

While the picker is active and you hover over elements, a translucent red overlay appears over the hovered element:

• The overlay has a 2px dashed red border.
• The background is semi-transparent red (20% opacity).
• The overlay is non-interactive — your clicks pass through to trigger selection.
• The overlay appears over all elements including text, images, buttons, and containers.

Note: The overlay does not appear over RTILA’s own UI elements (the refinement panel, recording controls, etc.).

---

Refinement Panel

After you click an element, the refinement panel enters refine mode. All elements matching the generated selector are highlighted in green with green borders.

Refinement Controls

Each highlighted element shows two small buttons:

Button	Icon	Action
Confirm	✓	Accept the current selector for ALL highlighted elements
Exclude	✗	Exclude this element (and its structural siblings) from the selection

Confirming the Selection

Click ✓ on any highlighted element to:

1. Accept the current CSS selector.
2. Stop the picking session.
3. Insert the selector into the input field.
4. Send the selector to the extension for further processing.

Excluding Elements

Click ✗ on a highlighted element to:

1. Identify the element’s structural position (parent, tag, classes, position).
2. Find all structurally similar elements (same parent type, same tag, same position).
3. Add a :not() exclusion for those elements.
4. Re-highlight the remaining matching elements.

Tip: If excluding an element leaves zero highlights, the refinement resets and you must start over. This prevents creating invalid selectors.

---

Excluding Elements Workflow

Here is a detailed example of excluding elements:

1. You click on a product card. All product cards are highlighted green.
2. You notice that ad cards are also highlighted (they have the same CSS class).
3. Click ✗ on one of the ad cards.
4. RTILA identifies that ad card’s structural position (e.g., it’s the 3rd div.product-card inside .container).
5. RTILA adds :not(:nth-of-type(3)) to the selector.
6. All ad cards at that position are removed from the highlights.
7. Review the remaining highlights. Click ✓ to confirm.

Note: Exclusion works by matching structural patterns, not specific element content. If ads appear at different positions, you may need to exclude each position separately.

---

Selector Generation Logic

RTILA generates selectors using a multi-strategy approach to ensure robustness. The generated selector is a comma-separated combination of multiple selector types:

Selector Format

css=<css_selector>,xpath=<xpath_expression>,text="<text_content>"

The engine tries each selector type in order and uses the first one that matches.

CSS Selector Generation

The CSS selector is generated by walking up the DOM tree from the target element:

1. Start with the element’s tag name.
2. Add stable attributes if available (data attributes, aria-label, role, name, title, alt, placeholder).
3. Add safe classes (non-dynamic classes).
4. Add :nth-of-type() if the element is not unique among siblings.
5. Walk up to the parent and repeat.
6. Stop when the selector is unique on the page.
7. Stop at html or body.

XPath Fallback

An XPath expression is generated as a fallback:

1. Start with the element’s tag name.
2. Add @id if available and stable.
3. Add stable attributes as predicates.
4. Add position predicates if needed.
5. Walk up to the parent and repeat.
6. Stop when the XPath is unique.

Text Selector

If the element has text content that is:

• Less than 60 characters
• Does not contain line breaks

A text="<content>" selector is appended as a third option.

---

Text Selection Mode

In addition to clicking elements, you can select text on the page:

1. Click the pointer icon to activate the picker.
2. Instead of clicking an element, highlight text on the page with your mouse.
3. Release the mouse button.
4. RTILA detects the text selection.
5. A text=<selected_text> selector is generated and sent to the extension.
6. The picker stops automatically.

Note: Text selection only works when you select a range of text. Single clicks still trigger element selection.

---

Tips Table

Tip	Description
Click precisely	Click directly on the element you want, not its parent container.
Use stable attributes	Elements with data-*, aria-label, or role attributes generate the most stable selectors.
Avoid dynamic content	Don’t select elements whose text changes frequently (counters, timestamps).
Use exclusion for ads	If ads share the same class as your target elements, use ✗ to exclude them.
Verify with the preview	After selecting, check the live preview to confirm the correct data is extracted.
Prefer containers	For datasets, select the parent container (e.g., the product card) as the item selector, not individual fields.
Combine with XPath	If CSS fails, the XPath fallback is tried automatically.
Text selectors are exact	Text selectors match exact text. Partial matches are not supported.
Test on multiple pages	Verify your selector works across different pages of the same site.
Avoid nth-child when possible	Position-based selectors break when content changes. Prefer class or attribute selectors.

---

Iframe Support

The element picker works within the main page context only. If the element you need is inside an iframe:

1. Select the element inside the iframe manually using the element picker (if the iframe is same-origin).
2. The generated selector will be relative to the iframe’s document.
3. In the command or property configuration, specify the iframe selector in the dedicated “Iframe” field.
4. The engine will navigate into the iframe before applying the element selector.

Note: Cross-origin iframes may not be accessible for element picking due to browser security restrictions. In this case, you may need to type the selector manually or use the AI extraction feature.

---

Dynamic Class Avoidance

RTILA includes intelligent logic to avoid dynamic CSS classes that change frequently and would break your selectors. The isDynamic function identifies and skips these patterns:

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

When RTILA encounters a class that matches any of these patterns, it skips it and uses other attributes or the element’s position instead.

---

Safe Classes

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

1. Splits the className string by whitespace.
2. Filters out classes that match isDynamic() patterns.
3. Filters out classes starting with known framework prefixes:
   • css- (CSS-in-JS libraries)
   • sc- (styled-components)
   • tw- (Tailwind CSS)
   • r- (React)
   • Mui (Material UI)
4. Filters out classes shorter than 3 characters.
5. Returns the remaining “safe” classes.

These safe classes are used in the generated CSS selector to ensure stability across page reloads and site updates.

---

Stable Attributes

The getStableAttributeSelector function checks for highly stable attributes before falling back to classes or position:

Priority Order

Priority	Attribute	Example
1	data-* attributes	data-product-id="12345"
2	aria-label	aria-label="Add to Cart"
3	role	role="button"
4	name	name="email"
5	id (if stable)	id="main-content"
6	title	title="View Details"
7	alt	alt="Product Image"
8	placeholder	placeholder="Enter email"

Attribute Value Handling

• Attribute values are escaped for special characters.
• Non-breaking spaces (\u00A0) are handled by using only the clean portion.
• Empty or whitespace-only attributes are skipped.
• Dynamic attribute values (matching isDynamic patterns) are skipped.

ID Stability Check

Element IDs are checked for stability before being used:

• IDs that are pure numbers are skipped (likely dynamic).
• IDs matching UUID patterns are skipped.
• IDs matching random alphanumeric patterns are skipped.
• IDs matching long hex strings are skipped.
• IDs with 4+ consecutive digits are skipped.

If the ID passes all checks, it is used as #escaped-id in the selector.

---

Complete Selector Example

For a product card element, the generated selector might look like:

css=div.product-card[data-product-id="12345"],xpath=//div[@data-product-id="12345"],text="Wireless Headphones"

When the engine processes this selector:

1. It first tries the CSS selector: div.product-card[data-product-id="12345"]
2. If that fails, it tries the XPath: //div[@data-product-id="12345"]
3. If that also fails, it tries the text selector: text="Wireless Headphones"

This multi-strategy approach ensures your selectors remain robust even when websites undergo minor structural changes.