Skip to main content
💡 Goal: \
  1. Selectors are the Frontend elements you point out to your users in your guides (e.g. to highlight or for them to click). \
  2. The Selector Picker and our Recorder Extension simplifies finding selectors by allowing direct element selection from web pages, eliminating the need for technical CSS selector knowledge.

​
What are selectors and what are best practices?

Selectors are the frontend elements your users should click on during the tour. In technical terms, they are CSS-style strings that tell Pyne exactly which DOM element to attach a tour step to. Under the hood, Pyne calls document.querySelector(selector) (or equivalent) to find and highlight the element. Key points:
  • CSS selectors: any valid CSS selector works (e.g. tag names, class selectors, attribute selectors, pseudo-classes).
  • Attribute selectors: the most stable option—e.g. CSS
    • [data-pyne-id="login-button"]
  • ID selectors: #my-element (but can collide if IDs are reused or autogenerated).
  • Class selectors: .btn.primary (brittle when styles change).
  • Avoid:
    • Deep combinators (.app > div:nth-child(3) > button)
    • XPath or index-based targeting
    • Anything tied to presentation (CSS classes, layout)

​
Best Practice for Product Tours

  1. Use a dedicated data-attribute (e.g. data-pyne-id, data-tour-id or your existing test-IDs).
  2. Keep selectors short & descriptive—reflect the element’s function, not its styling or position.
  3. Version-control your selector names alongside your components so any renames show up as code diffs.
With this approach, your tours remain rock-solid even as your UI evolves.

​
Recorder Extension

With our Recorder Chrome extension, you can record a walkthrough similar to how you would record a Loom. We will automatically transcribe everything you say, enrich it with our best practices, and attach the best selectors that we can find to the tour. Here’s a 2 mins video: https://www.youtube.com/watch?v=aiyA4POr57g

​
Selector Picker Extension

Once you are ready to edit your tour, you can use our Selector Picker to manually adjust selectors. If you cannot find stable selectors, you should ideally create unique selectors as described in step one.

​
How to Use the Selector Picker

ℹ️ What’s a Selector? A selector targets specific parts of a webpage (buttons, text fields, links, etc.). By choosing a selector for a guide step (like Highlight or User Click), you ensure the guide interacts with the correct element, making it accurate and easy to follow.
Demonstration Video:
Using the Picker:
  1. Add Step: When adding a step that requires an element (e.g., Highlight, User Click), it defaults to ‘Automatic’ selection mode.
  2. Initiate Selection: Click ‘Select element’.
  3. Enter URL: Input the URL of the webpage containing the target element. This URL is remembered for subsequent steps in the same guide.
  4. Hover & Highlight: Move your cursor over the webpage within the picker. Selectable elements will be outlined with a green dotted line.
  5. Click & Confirm: Click the desired element. It will remain highlighted. Confirm the selection using the confirmation bar at the bottom.

​
Navigating to Another Page within the Picker

If the target element is on a different page than the previous step:
  1. Enable Navigation Mode: Click ‘Navigate to Another Page’. Navigate Button
  2. Navigate: Use the picker interface to go to the correct page.
  3. Enable Selection Mode: Click ‘Select element’ again. Select Element Button
  4. Select & Confirm: Choose the desired element and confirm your selection.
💡 Quick Mode Switching Tip: Hold down Ctrl (Windows/Linux) or Cmd (Mac) to temporarily toggle between ‘Select element’ and ‘Navigate to Another Page’ modes. This helps select elements hidden in interactive components like dropdown menus.

​
Additional Considerations

  • Manual Fallback: If the Picker cannot identify a stable selector (due to website complexity), switch to ‘Manual’ mode to input a CSS selector or XPath directly.
  • Stability Issues: If a highlighted element cannot be saved, the extension deemed it unstable. Try selecting a parent element or use manual mode.
  • Maintenance: Websites change! Selectors identified by the Picker might break after updates. Test guides thoroughly, especially before launch and across different user accounts. Update selectors manually if needed, or contact the Pyne team for help.