Tour Component Library

Guide users through your app with a clean, modular tour experience.

Core Features

• Simple, step-based guidance
• Custom styling and theming
• Highlighting and drawing attention to specific UI elements

Component Architecture

Tour (Root)

Purpose: Controls overall visibility and step logic. Role: Hosts the full tour lifecycle and connects to context.

• Show/hide state management
• Step tracking and transitions
• Global backdrop control

TourContainer

Purpose: Wraps each step's visual content. Role: Ensures consistent positioning and layout.

• Overlay backdrop styling
• Responsive positioning logic
• Custom layout options

TourControls

Purpose: Lets users move forward, backward, or exit. Role: Separates navigation from content.

• Previous and Next navigation
• Skip to any step
• End tour early
• Customizable labels and buttons

TourStepContent

Purpose: Provides the specific text and visuals per step. Role: Keeps presentation separate from navigation.

• Smooth animated step content
• Flexible title/body formatting
• Multiple paragraph support
• Scoped styling

Navigation Methods

• Sequential: Move step-by-step using Next/Previous
• Direct Skip: Jump directly to a specific step
• Early Exit: Allow users to exit the tour at any time
• Keyboard Navigation: Use arrow keys or Escape to navigate

Theming Options

• Tailwind Classes: Apply custom styles via xClassName props
• Custom Rendering: Replace or extend internal components

Documentation

For detailed usage examples and API documentation, please refer to our Storybook documentation.

Getting Started

Install dependencies

yarn

Run Storybook

yarn storybook

Multiple Tours Support

The library supports defining and running multiple tours within a single application:

• Define different tours for different features or user journeys
• Start specific tours by ID
• Maintain separate completion state for each tour

Example:

// Define multiple tours
const appTours = {
  onboarding: {
    steps: [
      { title: "Welcome", content: ["First-time user introduction"] },
      // more steps...
    ],
  },
  "new-feature": {
    steps: [
      { title: "New Feature", content: ["Introducing our latest feature"] },
      // more steps...
    ],
  },
};

// Set up the provider with multiple tours
<TourProvider
  tours={appTours}
  defaultTourId="onboarding"
  pathname={pathname}
  navigate={navigate}
>
  <AppContent />
  <TourManager />
</TourProvider>;

// Start a specific tour
const { startTour } = useTour();
startTour("new-feature");

Tour Manager

The TourManager component connects to the tour context automatically, simplifying the implementation:

// Instead of manually passing all tour state:
<Tour
  steps={tourContext.steps}
  currentStepIndex={tourContext.currentStepIndex}
  isOpen={tourContext.isOpen}
  // ...other props
/>

// Simply use the TourManager within a TourProvider:
<TourManager
  // Only styling props should be passed if needed
  backdropClassName="custom-backdrop"
  containerClassName="custom-container"
/>