A modern, accessible, and performant React tour/onboarding library. A better alternative to react-joyride with zero legacy peer dependency issues.
npm install @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.



- 🚀 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
``bash`
npm install @bilalmohib7896/react-tour-guideor
yarn add @bilalmohib7896/react-tour-guideor
pnpm add @bilalmohib7896/react-tour-guide
`tsx
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:
return (
<>
run={run}
callback={(data) => {
if (data.status === "finished" || data.status === "skipped") {
setRun(false);
}
}}
/>
>
);
}
`
`tsx
import { Tour } from "@bilalmohib7896/react-tour-guide";
const steps = [
{
target: ".feature-1",
content:
function MyComponent() {
const [isRunning, setIsRunning] = useState(false);
return (
<>
run={isRunning}
callback={(data) => {
if (data.status === "finished" || data.status === "skipped") {
setIsRunning(false);
}
}}
/>
>
);
}
`
`tsx
import { useRef } from "react";
import { Tour } from "@bilalmohib7896/react-tour-guide";
function MyComponent() {
const buttonRef = useRef
const [run, setRun] = useState(false);
const steps = [
{
target: buttonRef,
content:
return (
<>
>
);
}
`
`tsx`
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}
/>
`tsx`
const steps = [
{
target: "#element-1",
content: Step 1,
placement: "auto", // Auto-detect best position
disableSpotlight: false,
disableScroll: false,
offset: {
top: 10,
left: 20,
},
},
{
target: "#element-2",
content: Step 2,
placement: "center", // Center in viewport
disableSpotlight: true, // No highlight
},
];
`tsxTour ${data.status}
run={run}
callback={(data) => {
switch (data.type) {
case "tour:start":
console.log("Tour started");
break;
case "tour:end":
console.log();Moved to step ${data.index}
break;
case "step:after":
console.log();Target not found for step ${data.index}
break;
case "target:notfound":
console.warn();`
break;
}
}}
/>
`tsx`
import "@tour-guide/react/styles";
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
`css
.tour-tooltip {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
border-radius: 12px;
}
.tour-button-primary {
background: white;
color: #667eea;
}
`
| 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 |
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| target | string \| RefObject | 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 | - | Custom data attributes |
`tsx`
type Placement = "top" | "bottom" | "left" | "right" | "center" | "auto";
`tsx``
interface TourCallbackProps {
status: "idle" | "running" | "paused" | "finished" | "skipped";
type: "tour:start" | "tour:end" | "step:before" | "step:after" | "target:notfound";
index?: number;
step?: TourStep;
}
| 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 |
Contributions are welcome! Please feel free to submit a Pull Request.
MIT © bilalmohib
Built with ❤️ for the React community. Inspired by the need for a modern, dependency-free tour library.