# How to Add a Guided Tour to a Bubble App

- Tool: Bubble
- Difficulty: Beginner
- Time required: 20-25 min
- Compatibility: All Bubble plans
- Last updated: March 2026

## TL;DR

A guided tour in Bubble uses a sequence of tooltip-like popups that highlight different UI elements and walk new users through your app. You track tour completion on the User record, trigger it on first login, and advance through steps using custom states. This can be built natively with Groups and conditionals or with an HTML-based tour library like Shepherd.js embedded in an HTML element.

## Overview: Guided Tours in Bubble

This tutorial shows you how to create an onboarding guided tour that walks new users through your app's key features. You will build step-by-step tooltips, track progress, and ensure the tour only appears for new users.

## Before you start

- A Bubble app with user authentication and a main dashboard page
- Understanding of custom states and conditional visibility
- Key UI elements that need explaining to new users

## Step-by-step guide

### 1. Add a 'has_completed_tour' field to the User type

In the Data tab, add a field 'has_completed_tour' (yes/no, default no) to the User Data Type. This tracks whether each user has seen the tour. On the dashboard page, add a 'Page is loaded' workflow with condition 'Only when Current User's has_completed_tour is no' that starts the tour.

**Expected result:** A flag on the User record controls whether the tour appears, triggering only for users who have not completed it.

### 2. Create tour step overlays with tooltip Groups

Add a semi-transparent overlay Group covering the full page (background black, 50% opacity). On top, add individual tooltip Groups for each tour step — small white cards with an arrow, title text, description text, and Next/Skip buttons. Position each tooltip near the UI element it explains. Use a page custom state 'tour_step' (number, default 1) to control which tooltip is visible: 'When page's tour_step is 1' shows tooltip 1, etc.

> Pro tip: Use a Floating Group for tooltips so they stay in position even if the page scrolls.

**Expected result:** A dark overlay with positioned tooltip cards appears for each tour step, shown one at a time based on the step state.

### 3. Highlight the target element for each step

To make the referenced UI element stand out through the overlay, add a conditional on the target element: 'When page's tour_step is [this step's number]' → set z-index higher than the overlay (add a CSS override via ID attribute). This makes the highlighted element appear above the dark overlay while everything else stays dimmed. Add a spotlight effect by giving the element a bright border or glow.

**Expected result:** Each tour step highlights the relevant UI element above the dark overlay, drawing the user's attention.

### 4. Wire up Next, Back, and Skip buttons

On each tooltip's 'Next' button, create a workflow that increments the 'tour_step' state by 1. On 'Back', decrement by 1. On 'Skip' or the final step's 'Done' button, set Current User's has_completed_tour to yes and hide the overlay. Add a progress indicator (Step 1 of 5) using the tour_step state. On the final step, change the Next button text to 'Get Started' and complete the tour.

**Expected result:** Users can navigate forward and backward through tour steps, skip the tour, or complete it to dismiss permanently.

### 5. Add a replay option in account settings

In the user's account settings or help section, add a 'Replay Tour' button. Its workflow: set Current User's has_completed_tour to no, then reload the page (Go to page → current page). The tour will trigger again on page load. This lets users who dismissed the tour early revisit it later.

**Expected result:** Users can restart the guided tour from their account settings at any time.

### 6. Alternative: embed Shepherd.js for a richer tour experience

For a more polished tour with smooth animations and automatic positioning, embed the Shepherd.js library via an HTML element. Add the Shepherd CSS and JS CDN links, then write a script that defines tour steps targeting Bubble elements by their ID attribute (set IDs in the element's property editor). Shepherd automatically positions tooltips and handles scrolling to elements. Use the Bubble JavaScript-to-Bubble bridge to update the has_completed_tour field on completion.

```
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/shepherd.js@11/dist/css/shepherd.css"/>
<script src="https://cdn.jsdelivr.net/npm/shepherd.js@11/dist/js/shepherd.min.js"></script>
<script>
const tour = new Shepherd.Tour({
  defaultStepOptions: {
    cancelIcon: { enabled: true },
    classes: 'shadow-md'
  }
});
tour.addStep({
  title: 'Welcome!',
  text: 'This is your dashboard. Let us show you around.',
  attachTo: { element: '#dashboard-header', on: 'bottom' },
  buttons: [{ text: 'Next', action: tour.next }]
});
tour.start();
</script>
```

**Expected result:** A polished guided tour with automatic positioning and animations runs using the Shepherd.js library.

## Complete code example

File: `Workflow summary`

```text
GUIDED TOUR — WORKFLOW SUMMARY
=================================

USER FIELD: has_completed_tour (yes/no, default no)
PAGE STATE: tour_step (number, default 1)

TRIGGER TOUR:
  Event: Page is loaded
  Condition: Current User's has_completed_tour = no
  Action: Show overlay, set tour_step = 1

TOUR ELEMENTS:
  Overlay Group: full page, black 50% opacity
  Tooltip Groups: white cards with arrow
    Each visible when tour_step = its number
  Target elements: z-index above overlay per step

NAVIGATION:
  Next button: tour_step = tour_step + 1
  Back button: tour_step = tour_step - 1
  Skip button: has_completed_tour = yes, hide overlay
  Done (last step): has_completed_tour = yes, hide

REPLAY:
  Settings → Replay Tour button
  Set has_completed_tour = no → reload page

ALTERNATIVE: Shepherd.js
  Embed via HTML element
  Target elements by ID attribute
  Auto-positions tooltips with animations
```

## Common mistakes

- **Showing the tour on every page load without checking completion** — Users see the tour repeatedly every time they visit, which is frustrating for returning users Fix: Always check 'has_completed_tour is no' before triggering the tour
- **Not assigning ID attributes to target elements** — JavaScript-based tour libraries need element IDs to attach tooltips — without them, the tour cannot find the elements Fix: Set the ID attribute in each target element's property editor (e.g., 'dashboard-header', 'nav-menu')
- **Hardcoding tooltip positions that break on different screen sizes** — Fixed pixel positions look wrong on mobile or different resolutions Fix: Use Floating Groups with responsive positioning, or use Shepherd.js which auto-calculates positions

## Best practices

- Track tour completion on the User record to prevent repeat displays
- Keep tours short — 3-5 steps covering only the most important features
- Add a Skip button so experienced users can dismiss immediately
- Provide a Replay option in settings for users who want to revisit
- Highlight only one element per step to maintain focus
- Use progressive disclosure — show basic features first, advanced ones later
- Test the tour on mobile screens to ensure tooltips are positioned correctly

## Frequently asked questions

### Should I use native Bubble Groups or a JavaScript library for the tour?

Use native Groups for simple 3-5 step tours. Use Shepherd.js or Intro.js for more than 5 steps or when you need automatic positioning and scroll-to features.

### Can I show different tours for different user roles?

Yes. Add a condition to check the user's role and trigger different tour sequences (e.g., admin tour vs regular user tour) based on the role.

### How do I handle the tour on mobile?

Keep tooltips simple and centered on mobile. Test positioning at mobile breakpoints. Consider a simpler full-screen card sequence instead of element-attached tooltips on small screens.

### Can I track which step users drop off at?

Yes. Log each step advance to a TourAnalytics Data Type. Compare completion rates per step to identify where users lose interest.

### Can RapidDev build custom onboarding experiences in Bubble?

Yes. RapidDev can design and build guided tours, onboarding wizards, contextual help systems, and interactive tutorials in Bubble.

---

Source: https://www.rapidevelopers.com/bubble-tutorial/implement-a-guided-tour-in-bubble
© RapidDev — https://www.rapidevelopers.com/bubble-tutorial/implement-a-guided-tour-in-bubble