Guided tour

Overview

How the guided tour works end to end.

• When a user first logs in and has not completed the tour, a welcome modal appears with Skip and Start tour buttons.
• Clicking "Start tour" launches a step-by-step popover sequence highlighting key UI elements (sidebar nav, search, area switcher, user menu, etc.).
• The tour is responsive: on desktop, steps target the sidebar navigation items directly. On mobile (below lg breakpoint), the first step targets the hamburger menu button instead.
• Completion is tracked in the database. Once a user completes or skips the tour, it does not appear again.

Welcome modal

The initial dialog shown before the tour begins. This uses a standard Driver.js popover without a highlighted element.

driver.highlight({
    popover: {
        title: 'Welcome to Koala 👋',
        description: 'Take a quick tour to learn where everything is.',
        showButtons: ['next', 'close'],
        nextBtnText: 'Start tour',
        closeBtnText: 'Skip',
        onCloseClick: function() { completeTour(); driver.destroy(); },
        onNextClick: function() { driver.moveNext(); }
    }
});

Implementation notes

Technical details for developers working with the guided tour.

• Uses Driver.js 1.3.1 loaded via CDN in the shared layout.
• Tour steps are built dynamically based on viewport width and the current area (partner vs conveyancing), so only relevant UI elements are highlighted.
• On desktop, the sidebar is auto-expanded during the tour to ensure navigation items are visible as step targets.
• Completion posts to /api/guided-tour/complete which sets GuidedTourCompletedAt on the user entity.
• Both "Skip" and completing all steps trigger the completion endpoint, so the tour is only shown once per user.
• The Driver.js CSS is included in the layout: driver.js@1.3.1/dist/driver.css.