Next.js product tour libraries compared (2026).

// app/tour-provider.tsx — render <TourProvider> in app/layout.tsx
"use client";
import { NextStep, NextStepProvider, type Tour } from "nextstepjs";

const tours: Tour[] = [
  {
    tour: "onboarding",
    steps: [
      {
        title: "Start here",
        content: "Create your first project.",
        selector: "#new-project-btn",
        side: "bottom",
        showControls: true,
        showSkip: true,
        nextRoute: "/settings", // pushed via next/navigation
      },
      {
        title: "Bring the team",
        content: "Invite a teammate from settings.",
        selector: "#invite-field",
        selectorRetryAttempts: 10, // wait for the new route to render
        showControls: true,
      },
    ],
  },
];

const markDone = (tour: string | null) => localStorage.setItem(`tour:${tour}`, "done");

export function TourProvider({ children }: { children: React.ReactNode }) {
  return (
    <NextStepProvider>
      <NextStep
        steps={tours}
        onComplete={markDone}
        onSkip={(_step: number, tour: string | null) => markDone(tour)}
      >
        {children}
      </NextStep>
    </NextStepProvider>
  );
}

// Anywhere in a client component:
//   const { startNextStep } = useNextStep();
//   startNextStep("onboarding");

// app/layout.tsx
import { Onborda, OnbordaProvider } from "onborda";
import type { OnbordaProps } from "onborda";

const tours: OnbordaProps["steps"] = [
  {
    tour: "onboarding",
    steps: [
      {
        icon: null,
        title: "Your projects",
        content: "Everything you build lives here.",
        selector: "#projects-nav",
        side: "right",
        showControls: true,
        nextRoute: "/projects", // navigated with next/navigation
      },
      {
        icon: null,
        title: "Start here",
        content: "Create your first project.",
        selector: "#new-project-btn",
        side: "bottom",
        showControls: true,
      },
    ],
  },
];

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <OnbordaProvider>
          <Onborda steps={tours} shadowOpacity="0.6">
            {children}
          </Onborda>
        </OnbordaProvider>
      </body>
    </html>
  );
}

// In a client component:
//   const { startOnborda } = useOnborda();
//   startOnborda("onboarding");

"use client";
import { useState } from "react";
import { Joyride, STATUS } from "react-joyride"; // v3: named export

const steps = [
  { target: "#new-project-btn", content: "Everything starts here — create your first project." },
  { target: "#invite-field", content: "Onboarding sticks better with a teammate aboard." },
];

export function OnboardingTour() {
  const [run, setRun] = useState(true); // v3: run defaults to false

  return (
    <Joyride
      run={run}
      steps={steps}
      continuous
      options={{ showProgress: true, buttons: ["back", "skip", "primary"] }}
      onEvent={({ status }) => {
        if (status === STATUS.FINISHED || status === STATUS.SKIPPED) setRun(false);
      }}
    />
  );
}

"use client";
import { useEffect } from "react";
import { driver } from "driver.js";
import "driver.js/dist/driver.css";

export function OnboardingTour() {
  useEffect(() => {
    // driver() touches document, so it must run in the browser, after mount.
    if (localStorage.getItem("tour:onboarding")) return;
    let unmounting = false;
    const tour = driver({
      showProgress: true,
      steps: [
        {
          element: "#new-project-btn",
          popover: { title: "Start here", description: "Create your first project." },
        },
        {
          element: "#invite-field",
          popover: { title: "Bring the team", description: "Invite a teammate early." },
        },
      ],
      // Finished or closed: remember it. Skipped when React unmounts us.
      onDestroyed: () => {
        if (!unmounting) localStorage.setItem("tour:onboarding", "done");
      },
    });
    tour.drive();
    return () => {
      unmounting = true; // Strict Mode remounts, route changes
      tour.destroy();
    };
  }, []);

  return null;
}