@bilalmohib7896/react-tour-guide

A modern, accessible, and performant React tour/onboarding library. A better alternative to react-joyride with zero legacy peer dependency issues.

✨ Features

• 🚀 Zero Legacy Dependencies - No --force or --legacy-peer-deps needed
• 🎯 TypeScript First - Full TypeScript support with comprehensive types
• ♿ Accessible - Built with ARIA labels and keyboard navigation
• 🎨 Highly Customizable - Customize colors, styles, labels, and behavior
• 📱 Responsive - Works seamlessly on all screen sizes
• ⚡ Performant - Optimized with React hooks and efficient re-renders
• 🎭 Flexible - Support for CSS selectors or React refs
• ⌨️ Keyboard Navigation - Arrow keys and Escape support
• 🎪 Auto Positioning - Smart tooltip placement with auto-detection
• 🎬 Smooth Animations - Polished transitions and effects
• 🔒 Production Ready - Battle-tested and ready for enterprise use

📦 Installation

npm install @bilalmohib7896/react-tour-guide
# or
yarn add @bilalmohib7896/react-tour-guide
# or
pnpm add @bilalmohib7896/react-tour-guide

🚀 Quick Start

import { Tour } from "@bilalmohib7896/react-tour-guide";
import "@bilalmohib7896/react-tour-guide/styles.css"; // Optional: import default styles

function App() {
  const [run, setRun] = useState(false);

  const steps = [
    {
      target: "#my-button",
      content: <div>This is the first step!</div>,
      placement: "bottom",
    },
    {
      target: "#my-input",
      content: <div>This is the second step!</div>,
      placement: "right",
    },
  ];

  return (
    <>
      <button onClick={() => setRun(true)}>Start Tour</button>
      <Tour
        steps={steps}
        run={run}
        callback={(data) => {
          if (data.status === "finished" || data.status === "skipped") {
            setRun(false);
          }
        }}
      />
    </>
  );
}

📚 Documentation

Basic Usage

import { Tour } from "@bilalmohib7896/react-tour-guide";

const steps = [
  {
    target: ".feature-1",
    content: <h3>Welcome to Feature 1</h3>,
    placement: "bottom",
  },
  {
    target: ".feature-2",
    content: <h3>This is Feature 2</h3>,
    placement: "right",
  },
];

function MyComponent() {
  const [isRunning, setIsRunning] = useState(false);

  return (
    <>
      <button onClick={() => setIsRunning(true)}>Start Tour</button>
      <Tour
        steps={steps}
        run={isRunning}
        callback={(data) => {
          if (data.status === "finished" || data.status === "skipped") {
            setIsRunning(false);
          }
        }}
      />
    </>
  );
}

Using React Refs

import { useRef } from "react";
import { Tour } from "@bilalmohib7896/react-tour-guide";

function MyComponent() {
  const buttonRef = useRef<HTMLButtonElement>(null);
  const [run, setRun] = useState(false);

  const steps = [
    {
      target: buttonRef,
      content: <div>This button does something special!</div>,
    },
  ];

  return (
    <>
      <button ref={buttonRef}>Click me</button>
      <Tour steps={steps} run={run} />
    </>
  );
}

Customization

<Tour
  steps={steps}
  run={run}
  primaryColor="#FF6B6B"
  overlayOpacity={0.7}
  showProgress={true}
  showSkipButton={true}
  showBackButton={true}
  labels={{
    next: "Continue",
    back: "Previous",
    skip: "Skip Tour",
    finish: "Complete",
  }}
  className={{
    tooltip: "custom-tooltip-class",
    overlay: "custom-overlay-class",
  }}
  keyboardNavigation={true}
  disableBodyScroll={false}
/>

Advanced: Step Configuration

const steps = [
  {
    target: "#element-1",
    content: <div>Step 1</div>,
    placement: "auto", // Auto-detect best position
    disableSpotlight: false,
    disableScroll: false,
    offset: {
      top: 10,
      left: 20,
    },
  },
  {
    target: "#element-2",
    content: <div>Step 2</div>,
    placement: "center", // Center in viewport
    disableSpotlight: true, // No highlight
  },
];

Callback Handling

<Tour
  steps={steps}
  run={run}
  callback={(data) => {
    switch (data.type) {
      case "tour:start":
        console.log("Tour started");
        break;
      case "tour:end":
        console.log(`Tour ${data.status}`);
        break;
      case "step:after":
        console.log(`Moved to step ${data.index}`);
        break;
      case "target:notfound":
        console.warn(`Target not found for step ${data.index}`);
        break;
    }
  }}
/>

🎨 Styling

Using Default Styles

import "@tour-guide/react/styles";

Custom Styling

The component uses semantic class names that you can override:

• .tour-overlay - Overlay backdrop
• .tour-tooltip - Tooltip container
• .tour-progress - Progress indicator
• .tour-content - Step content
• .tour-actions - Action buttons container
• .tour-button-primary - Primary button (Next/Finish)
• .tour-button-back - Back button
• .tour-button-skip - Skip button

.tour-tooltip {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  border-radius: 12px;
}

.tour-button-primary {
  background: white;
  color: #667eea;
}

📖 API Reference

Tour Component Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | steps | TourStep[] | required | Array of tour steps | | run | boolean | false | Whether the tour is running | | stepIndex | number | 0 | Initial step index | | continuous | boolean | true | Auto-proceed to next step | | showProgress | boolean | true | Show progress indicator | | showSkipButton | boolean | true | Show skip button | | showBackButton | boolean | true | Show back button | | callback | (data: TourCallbackProps) => void | - | Callback for tour events | | primaryColor | string | "#0F6CBD" | Primary color for buttons/highlights | | zIndex | number | 10000 | Z-index for overlay and tooltip | | overlayOpacity | number | 0.5 | Overlay opacity (0-1) | | disableOverlayClose | boolean | false | Disable closing on overlay click | | className | object | - | Custom class names | | labels | object | - | Custom button labels | | keyboardNavigation | boolean | true | Enable keyboard navigation | | scrollPadding | number | 20 | Scroll padding when scrolling to target | | disableBodyScroll | boolean | false | Disable body scroll when tour is active | | spotlightPadding | number | 8 | Spotlight padding around element | | spotlightBorderRadius | number | 8 | Spotlight border radius |

TourStep Interface

| Property | Type | Default | Description | |----------|------|---------|-------------| | target | string \| RefObject<HTMLElement> | required | CSS selector or React ref | | content | ReactNode | required | Step content | | placement | Placement | "bottom" | Tooltip placement | | disableSpotlight | boolean | false | Disable spotlight for this step | | disableScroll | boolean | false | Disable scrolling to target | | offset | { top?: number; left?: number } | - | Custom tooltip offset | | data | Record<string, string> | - | Custom data attributes |

Placement Type

type Placement = "top" | "bottom" | "left" | "right" | "center" | "auto";

TourCallbackProps Interface

interface TourCallbackProps {
  status: "idle" | "running" | "paused" | "finished" | "skipped";
  type: "tour:start" | "tour:end" | "step:before" | "step:after" | "target:notfound";
  index?: number;
  step?: TourStep;
}

🎯 Comparison with react-joyride

| Feature | @bilalmohib7896/react-tour-guide | react-joyride | |---------|------------------|---------------| | Modern Dependencies | ✅ Yes | ❌ Requires --legacy-peer-deps | | TypeScript Support | ✅ Full | ⚠️ Partial | | React 18+ Support | ✅ Yes | ⚠️ Issues | | Bundle Size | ✅ Smaller | ⚠️ Larger | | Accessibility | ✅ Built-in | ⚠️ Limited | | Customization | ✅ Extensive | ⚠️ Moderate | | Performance | ✅ Optimized | ⚠️ Can be slow | | Maintenance | ✅ Active | ⚠️ Slower updates |

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

MIT © bilalmohib

🙏 Acknowledgments

Built with ❤️ for the React community. Inspired by the need for a modern, dependency-free tour library.