DOCSEARCHbyAlgolia
Submit Docs

shadcn/tour

repository·main·Indexed 43 days ago

https://github.com/niazmorshed2007/shadcn-tour

A React component library for creating interactive product tours using motion and shadcn/ui components. It allows developers to highlight specific DOM elements with a spotlight effect and guide users through application features using the TourProvider, TourAlertDialog, and useTour hook. Version 0.2.0.

Tokens
2K
Snippets
8
Records
9
Agent score
5%

What's inside shadcn-tour

  1. How multiple named tours work

    main

    You can register multiple distinct tours by passing an array of TourDefinition objects to the tours prop on TourProvider. Each definition requires a unique id and an array of steps.

    To trigger a specific tour, use the startTour(tourId) method from the useTour hook.

    import { TourProvider, TourDefinition } from "@/components/tour";

const tours: TourDefinition[] = [
  { id: "intro", steps: introSteps },
  { id: "advanced", steps: advancedSteps },
];

// Setup Provider
<TourProvider
  tours={tours}
  onComplete={(tourId) => console.log(`${tourId} completed`)}
>
  {children}
</TourProvider>

// Triggering a tour
const { startTour } = useTour();
<button onClick={() => startTour("intro")}>Start Intro Tour</button>

  2. Set up TourProvider

    main

    Wrap your application (or a specific part of it) with TourProvider to make the tour functionality available throughout your component tree. This is typically done in your root layout file.

    import { TourProvider } from "@/components/tour";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <TourProvider>{children}</TourProvider>;
}

  3. Create a single-tour walkthrough

    main

    For a simple single-tour setup, use the setSteps function from the useTour hook to define your steps and the TourAlertDialog component to trigger the tour UI.

    Important: Ensure the elements you want to highlight have an id matching the selectorId provided in your steps.

    const steps: TourStep[] = [
  {
    content: <div>Team Switcher</div>,
    selectorId: TOUR_STEP_IDS.TEAM_SWITCHER,
    position: "right",
    onClickWithinArea: () => { },
  },
  {
    content: <div>Writing Area</div>,
    selectorId: TOUR_STEP_IDS.WRITING_AREA,
    position: "left",
    onClickWithinArea: () => { },
  },
];

function Page() {
  const { setSteps } = useTour();
  const [openTour, setOpenTour] = useState(false);

  useEffect(() => {
    setSteps(steps);
    const timer = setTimeout(() => {
      setOpenTour(true);
    }, 100);

    return () => clearTimeout(timer);
  }, [setSteps]);

  return <div>
    <TourAlertDialog open={openTour} onOpenChange={setOpenTour} />
  </div>;
}

// In your component tree:
<div id={TOUR_STEP_IDS.TEAM_SWITCHER}>Team Switcher</div

  4. Install shadcn/tour

    main

    Install the necessary components and hooks by running the shadcn CLI command. This will add TourProvider, TourAlertDialog, and the useTour hook to your components/tour.tsx file, and a set of step IDs to lib/tour-constants.ts.

    Note that TOUR_STEPS is the constant containing step IDs. Each step ID must be assigned to a DOM element's id to serve as the selector for the spotlight highlight.

    pnpx shadcn add https://tour.niazmorshed.dev/tour.json

  5. Configure TourStep properties

    main

    The TourStep object defines the behavior and appearance of an individual step.

    Key configuration options include:

    • content: The React node to display in the tooltip.
    • selectorId: The id of the target element to highlight.
    • position: Tooltip placement ("top", "bottom", "left", or "right").
    • padding & borderRadius: Controls the spotlight cutout shape.
    • showSkip: Controls visibility of the 'Skip tour' button.
    • closeable: Overrides the global closeable setting for an 'X' button.
    • onClickWithinArea: A callback triggered when the user clicks inside the highlighted element.
    const steps: TourStep[] = [
  {
    content: <div>This element has a rounded spotlight</div>,
    selectorId: "my-element",
    padding: 12,
    borderRadius: 16,
    showSkip: false,
    closeable: true,
  },
];

  6. Use TourAlertDialog

    main

    The TourAlertDialog is a component used to prompt users to begin or skip a tour. It is typically controlled via local state.

    const [openTour, setOpenTour] = useState(false);

<TourAlertDialog open={openTour} onOpenChange={setOpenTour} />

  7. Use the useTour hook

    main

    The useTour hook provides the state and control functions for the active tour. It must be used within a TourProvider.

    Returned Values:

    • isActive: Boolean indicating if a tour is running.
    • currentStep: Current step index (-1 if inactive).
    • totalSteps: Total number of steps.
    • startTour(tourId?: string): Starts a tour (by ID if multiple tours are registered).
    • nextStep() / previousStep(): Navigation functions.
    • endTour(): Ends the current tour.
    • setSteps(steps: TourStep[]): Sets steps for single-tour usage.
    • isTourCompleted / setIsTourCompleted: Access and modify completion status.
    • activeTourId: The ID of the currently running tour.
    const { startTour, currentStep, nextStep, activeTourId } = useTour();

  8. Configure TourProvider lifecycle and global settings

    main

    The TourProvider manages the global state and provides lifecycle hooks.

    Global Props:

    • tours: Array of TourDefinition for multiple named tours.
    • closeable: Boolean to enable an 'X' close button on all tooltips.
    • onStart, onStepChange, onComplete, onSkip: Callbacks that receive tourId (and step index for change/skip/complete) as arguments.
    • isTourCompleted: Initial state for tour completion status.
    <TourProvider
  tours={tours}
  onStart={(tourId) => console.log(`${tourId} started`)}
  onStepChange={(tourId, step) => console.log(`${tourId} moved to step ${step}`)}
  onComplete={(tourId) => console.log(`${tourId} completed`)}
  onSkip={(tourId, step) => console.log(`${tourId} skipped at step ${step}`)}
  closeable
>
  {children}
</TourProvider>

  9. Keyboard Navigation for Tours

    main

    When a tour is active, users can navigate using the following keyboard shortcuts:

    • ArrowRight: Advance to the next step.
    • ArrowLeft: Go back to the previous step.
    • Escape: Skip or dismiss the tour.