Guides

Trigger product tours from page elements

Element triggers let an auto-start tour wait for something happening in your product before it starts. Use them for modals, buttons, inputs, and UI states that are more specific than a page URL.

When to use page element triggers

Use a page element trigger when a tour should start after a visitor reaches a specific state in your interface.

Common examples:

  • Start a tour when an upgrade modal appears.
  • Wait until a visitor clicks a specific button.
  • Show guidance after an input is filled out.
  • Hold a tour until a sidebar, drawer, or empty state is present.
  • Start only when a button becomes enabled.

Tip

If you only need a tour to run on a page, use page targeting. Add a page element trigger when the page URL is not specific enough.

Before you start

Make sure you have installed Hopscotch in your app and that your tour points to the page where the element can appear.

Element-triggered tours also need Auto-start this tour turned on. If auto-start is turned off, the tour can still be launched manually from a launcher item, a data-hopscotch-tour-id button, or the Browser SDK, but page element conditions will not start the tour automatically.

Use stable CSS selectors for your trigger elements. Handwritten IDs, such as #upgrade-modal or #invite-team-button, are usually safer than generated class names. For more selector guidance, see My product tour is not starting.

Add a page element trigger

  1. Open the tour in Hopscotch.
  2. In the start settings, keep Auto-start this tour checked.
  3. Choose the tour frequency:
    • Only once for most onboarding tours.
    • Once per session for reminders that can repeat in a new browser session.
    • Every page load for debugging or internal testing.
  4. Set the audience to Custom.
  5. Add a condition and choose Page Element.
  6. Enter the CSS selector Hopscotch should watch.
  7. Choose the element state that should trigger the tour.
  8. Save the tour and make sure it is active when you are ready for visitors to see it.

Hopscotch still checks the tour URL, frequency, and audience rules. The tour starts only when those rules match and the page element condition is met.

Element states you can watch

Element stateUse it when
Is present in the DOMThe tour should start when a modal, sidebar, button, or other element exists on the page.
Is not in the DOMThe tour should start only while a selector is absent from the page.
Is clickedThe tour should start after a visitor clicks the matching element.
Is disabledThe tour should start when a button or input is disabled.
Is not disabledThe tour should start when a button or input becomes available.
Input has any valueThe tour should start after a visitor enters something in an input.
Input equalsThe tour should start when an input value exactly matches the value you provide.
Input containsThe tour should start when an input value contains the text you provide.

DOM vs. visibility

"Present" means the element exists in the page DOM. An element that is hidden with CSS may still count as present. If you need a trigger to reflect visibility, ask your team to add or remove a stable element in the UI state you want to target.

Combine triggers with other targeting

Page element triggers can be combined with the rest of Hopscotch's targeting rules.

For example, you can show a tour only when:

  • The visitor is on /billing.
  • The visitor is on a paid plan.
  • The visitor has not seen the tour before.
  • #upgrade-modal is present in the DOM.

If you add multiple conditions, the AND/OR grouping in the condition builder controls how they work together.

Preview and test an element-triggered tour

When a tour has a page element condition, the preview flow can either start immediately or wait for the trigger.

  1. Open the tour in Hopscotch.
  2. Click the preview option.
  3. If Hopscotch asks for a preview URL and the tour has element conditions, check Wait for trigger conditions.
  4. Open the preview and reproduce the UI state, such as opening the modal or clicking the watched button.
  5. Confirm the tour starts only after the trigger condition is met.

Leave Wait for trigger conditions unchecked when you only want to review the tour copy, step order, or styling. In that mode, the preview starts immediately.

Preview starts, exits, and completions do not count in visitor analytics. To test the published visitor experience, use a fresh tab, browser window, or incognito window after previewing.

Troubleshooting

If the tour starts immediately, check whether the condition is already true when the page loads. For example, an "is present" trigger starts as soon as the selector exists, and an "is not in the DOM" trigger starts as soon as the selector is absent.

If the tour never starts, confirm these items:

  • Auto-start this tour is checked.
  • The tour is active and saved.
  • The page URL and audience rules match the visitor you are testing with.
  • The CSS selector exists on the page when the condition should be true.
  • For click triggers, the visitor clicks the element that matches the selector.
  • For input triggers, the selector points to the input whose value should be checked.

For more debugging steps, see My product tour is not starting.

Still have questions?

We are here to help. Don't hesitate to reach out by email any time.

Next
Preview and test tours