@automatiseerjouwproces/nilo-tours

Nilo Tours is a lightweight in-app tour system for guiding users through your application UI.
No external tour libraries are used.

Installation

pnpm add @automatiseerjouwproces/nilo-tours

Provider usage

Wrap your app with the provider. For Next.js, do this in a client-side provider wrapper.

"use client";

import { NiloTourProvider } from "@automatiseerjouwproces/nilo-tours";
import { useRouter } from "next/navigation";

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();

  return (
    <NiloTourProvider
      options={{
        name: "onboarding",
        persist: true,
        navigate: (route) => router.push(route),
      }}
    >
      {children}
    </NiloTourProvider>
  );
}

Hook usage

import { useNiloTour } from "@automatiseerjouwproces/nilo-tours";

const { startTour, next, previous, stopTour, currentStep } = useNiloTour();

Example tour

import type { TourStep } from "@automatiseerjouwproces/nilo-tours";
import { useNiloTour } from "@automatiseerjouwproces/nilo-tours";

const steps: TourStep[] = [
  {
    id: "intro",
    target: "#welcome",
    title: "Welkom",
    content: "Dit is de start van de tour.",
    placement: "bottom",
  },
  {
    id: "settings",
    target: "#settings",
    content: "Pas hier je instellingen aan.",
    placement: "right",
    scrollTo: true,
  },
];

export function StartTourButton() {
  const { startTour } = useNiloTour();
  return <button onClick={() => startTour(steps)}>Start tour</button>;
}

Cross-route tour steps (Next.js)

If a step has nextRoute, the provider will navigate and wait for the next step target.

const steps: TourStep[] = [
  {
    id: "route",
    target: "#next-link",
    content: "We gaan naar de volgende route.",
    nextRoute: "/tour/second",
  },
  {
    id: "finish",
    target: "#tour-secondary-card",
    content: "Doel gevonden op de nieuwe route.",
  },
];

API

TourStep

• id (string)
• target (string | HTMLElement)
• content (ReactNode)
• title (ReactNode, optional)
• placement ("top" | "bottom" | "left" | "right" | "auto")
• scrollTo (boolean)
• allowInteract (boolean)
• nextRoute (string)
• padding (number)

Provider options

• name (string) - used for localStorage persistence
• persist (boolean)
• persistKey (string)
• waitForTargetMs (number)
• routeChangeTimeoutMs (number)
• navigate ((route: string) => Promise | void)

Hook return

• startTour(steps)
• stopTour()
• next()
• previous()
• goToStep(index)
• currentStep
• currentStepIndex
• isActive
• isPausedForRoute