Selectors Guide

You don’t need to be an expert to use selectors. If you can inspect an element, you can create a tour.

🚀 Quick Start (Do This First)

1. Right-click any element on your page
2. Click **Inspect**
3. Find the element in the HTML
4. Use one of these:

• `#id` → if element has an id
• `.class` → if it has a class
• `button` / `div` → basic tags

Example:

{
  selector: "#login-btn"
}

🧠 Simple Rules (Follow These)

• Prefer **id (`#id`)** → most stable
• Use **class (`.class`)** if no id
• Avoid deep selectors like:

div > div > span:nth-child(2)

👉 These break easily

✅ Best Practices

1. Use Unique Selectors

Good:

#submit-btn

Bad:

.button

2. Add Your Own Attributes (Recommended)

If your UI doesn’t have good selectors, add this:

<button data-tour="start-btn">Start</button>

Then use:

{
  selector: '[data-tour="start-btn"]'
}

👉 This is the most reliable method

3. Keep It Stable

Avoid:

• Auto-generated class names
• Framework-specific dynamic ids

🔍 Common Selector Types

ID Selector

#header

Class Selector

.navbar

Attribute Selector (Best for production)

[data-tour="menu"]

Tag Selector

button

⚡ Extended Selector Features (NavigateMe)

These are power features that make your tours smarter and easier to target.

🔤 `:contains(text)`

Select elements containing specific text.

button:contains(Start)

👉 Matches any button that includes "Start"

🎯 `:exact`

Use with :contains() for exact text match.

button:contains(Start):exact

👉 Matches only elements with exact text "Start"

🔢 `:nth(index)`

Select element at a specific position (0-based index).

.card:nth(2)

👉 Selects the 3rd .card

🔚 `:last`

Select the last matching element.

.card:last

👉 Selects the last .card

🧪 Combining Features

You can combine selectors with features:

button:contains(Next):nth(1)

👉 Second button containing "Next"

.menu-item:contains(Settings):exact

👉 Exact match for "Settings"

⚠️ Guidelines for Extended Selectors

• Use `:contains()` when no id/class is available
• Use `:exact` to avoid wrong matches
• Use `:nth()` when multiple elements exist
• Prefer `[data-tour]` over complex logic when possible

🧪 Debugging Tips

Element not found?

• Check selector syntax
• Ensure element exists on load
• Try removing advanced filters (`:nth`, `:contains`)

Wrong element selected?

• Add `:exact`
• Use `:nth()`
• Switch to `[data-tour]`

💡 Pro Tip

Start simple → refine later

Don’t over-engineer selectors. Get the tour working first, then improve.

🎯 Example Tour Step

{
  selector: 'button:contains(Login):exact',
  content: "Click here to login"
}

🚀 Summary

• Use `#id` when possible
• Use `[data-tour="..."]` for reliability
• Use `:contains`, `:exact`, `:nth`, `:last` when needed
• Avoid complex CSS chains

That’s it. You’re ready to build powerful, flexible tours.