DEV Community

Cover image for Add an onboarding tour to any React/Next.js app in 5 minutes
Raj Chavan
Raj Chavan

Posted on

Add an onboarding tour to any React/Next.js app in 5 minutes

#webdev #nextjs #react #productivity

Add an onboarding tour to any React/Next.js app in 5 minutes

Most apps have zero onboarding.

Users land on your dashboard, look around confused, and leave.

The problem? Existing tools like Intercom cost $300+/month. Shepherd.js requires writing hundreds of lines of config. Intro.js feels outdated.

I built TourKit to fix this. One script tag. Configure from a dashboard. Works on any website.

Here's how to add it to your React or Next.js app in 5 minutes.

What you'll build

A guided onboarding tour that:

  • Highlights specific elements on your page
  • Shows tooltips with title and message
  • Tracks completion in analytics
  • Never repeats for returning users
  • Works on mobile with bottom sheet UI

Step 1 — Create a free account

Go to tourkit-phi.vercel.app and sign up.

Create a new project:

  • Project name: My App
  • Domain: yourapp.com

You'll get a unique script key. Copy it.

Step 2 — Install the script tag

For Next.js (App Router)

Add to your root app/layout.js:

import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script
          src="https://cdn.jsdelivr.net/gh/webdev-raj/Tourkit@sdk-v13/sdk/dist/tourkit.min.js"
          data-key="YOUR_SCRIPT_KEY"
          data-api="https://tourkit-phi.vercel.app"
          strategy="afterInteractive"
        />
      </body>
    </html>
  )
}
Enter fullscreen mode Exit fullscreen mode

For React (Create React App / Vite)

Add to your public/index.html before </body>:

<script
  src="https://cdn.jsdelivr.net/gh/webdev-raj/Tourkit@sdk-v13/sdk/dist/tourkit.min.js"
  data-key="YOUR_SCRIPT_KEY"
  data-api="https://tourkit-phi.vercel.app"
  async>
</script>
Enter fullscreen mode Exit fullscreen mode

Replace YOUR_SCRIPT_KEY with the key from your TourKit dashboard.

Step 3 — Add TourKitProvider for route changes

React and Next.js use client-side routing. The page URL changes without a full reload.

Without this, TourKit only runs on initial page load and misses route changes.

Next.js (App Router)

Create components/TourKitProvider.jsx:

'use client'
import { useEffect } from 'react'
import { usePathname } from 'next/navigation'

export default function TourKitProvider() {
  const pathname = usePathname()

  useEffect(() => {
    const timer = setTimeout(() => {
      window.TourKit?.startFor(pathname)
    }, 500)
    return () => clearTimeout(timer)
  }, [pathname])

  return null
}
Enter fullscreen mode Exit fullscreen mode

Add to app/layout.js:

import TourKitProvider from '@/components/TourKitProvider'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <TourKitProvider />
        {children}
        <Script ... />
      </body>
    </html>
  )
}
Enter fullscreen mode Exit fullscreen mode

React Router 

import { useEffect } from 'react'
import { useLocation } from 'react-router-dom'

export default function TourKitProvider() {
  const location = useLocation()

  useEffect(() => {
    const timer = setTimeout(() => {
      window.TourKit?.startFor(location.pathname)
    }, 500)
    return () => clearTimeout(timer)
  }, [location.pathname])

  return null
}
Enter fullscreen mode Exit fullscreen mode

Add inside your <BrowserRouter>:

<BrowserRouter>
  <TourKitProvider />
  <App />
</BrowserRouter>
Enter fullscreen mode Exit fullscreen mode

Step 4 — Configure your tour steps

Go back to your TourKit dashboard.

Open your project → click Edit Tour.

Add your first step:

  • Title: Welcome to MyApp
  • Message: This is your main dashboard where you manage everything.
  • CSS Selector: .dashboard-header
  • Position: bottom

Add more steps for key features:

Step 1: .dashboard-header → "Welcome to MyApp"
Step 2: .sidebar-nav → "Navigate between sections here"
Step 3: .create-btn → "Click here to create your first item"
Step 4: .settings-link → "Customize your account here"

Finding the right CSS selector:

Open Chrome DevTools (F12) → right click any element → Inspect → copy the selector.

Common selectors:

nav → navigation bar
.sidebar → sidebar
#dashboard → element with id="dashboard"
.btn-primary → primary button
header → page header

Step 5 — Test your tour

Click Live Demo on your project page.

This opens a sandbox with multiple pages to test your tour without touching your real website.

Or load your actual app and the tour will appear automatically for first-time visitors.

To replay during testing, run in browser console:

window.TourKit.resetAll()
Enter fullscreen mode Exit fullscreen mode

Bonus — Context-aware tours

Different pages can have different tours.

In the step editor, set a Trigger URL:

Step 1: no URL → shows on / (homepage)
Step 2: /dashboard → shows on dashboard only
Step 3: /settings → shows on settings only
Step 4: /products/[id] → shows on any product page

Each page gets its own focused tour. Users only see what's relevant to where they are.

Dynamic URL segments are supported:

/products/[id] → matches /products/123
/blog/[category]/[slug]→ matches /blog/tech/my-post
/dashboard/* → matches all dashboard pages

What the tour looks like

On desktop:

  • Spotlight overlay highlights the element
  • Tooltip appears next to it
  • Smooth transitions between steps

On mobile:

  • Element highlighted at top
  • Tooltip slides up as a bottom sheet
  • Large tap targets for buttons

The TourKit API

After installation, these methods are available globally:

// Start tour for current page
window.TourKit.start()

// Start tour for specific page
window.TourKit.startFor('/dashboard')

// Destroy active tour
window.TourKit.destroy()

// Reset seen flag for current page
window.TourKit.reset()

// Reset all seen flags
window.TourKit.resetAll()
Enter fullscreen mode Exit fullscreen mode

Analytics

TourKit automatically tracks:

  • Tour started
  • Each step viewed
  • Tour completed
  • Tour skipped

View analytics per project in your dashboard.
See completion rates and step dropoff.

Pricing

  • Free — 1 project, 500 sessions/month
  • Starter — $9/mo, 3 projects, 2000 sessions
  • Pro — $19/mo, unlimited + AI tour generator

Start free at tourkit-phi.vercel.app

Summary

In 5 minutes, you can have a fully working onboarding tour on your React or Next.js app:

  1. ✅ Create project → get script key
  2. ✅ Add script tag to layout
  3. ✅ Add TourKitProvider for route changes
  4. ✅ Configure steps from the dashboard
  5. ✅ Test on live demo page

No framework lock-in. No complex config. One script tag.

If you try it, let me know how it goes.

Happy to help with CSS selectors or any setup questions in the comments.

Live Here - Tourkit

Top comments (0)