[!WARNING] 🚧 Under Active Development

This library is currently in early development and not recommended for production use yet. APIs may change, and there might be bugs or incomplete features.

We're looking for contributors and maintainers! If you're interested in helping shape this library, please check out our Contributing Guide or open an issue to get involved. Your contributions are highly valued! 🙏

🎬 See It In Action

🌟 Why Choose React Native Tour Guide?

| Feature | This Library | Other Solutions | | -------------------------- | ---------------------------- | --------------------- | | 🎯 Setup Time | < 1 minute | 10-30 minutes | | 🎨 Customization | Fully customizable | Limited options | | 📱 Platform Support | iOS & Android | Platform specific | | 🚀 Expo & CLI Support | Both supported | Limited | | 🏗️ New Architecture | Fully compatible | Not supported | | 🔌 Native Dependencies | Zero (optional enhancements) | Multiple required | | 📦 Bundle Size | Minimal (< 50KB) | Heavy (> 200KB) | | 🎭 Custom Components | Full support | Limited/None | | 🔄 Auto Scrolling | Built-in | Manual implementation | | 📚 TypeScript | Full support | Partial/None | | 🌈 Visual Effects | Optional (Blur, Gradient) | None/Required | | ⚡ Performance | Hardware accelerated | CPU intensive |

📚 Table of Contents

• 🌟 Why Choose React Native Tour Guide?
• ✨ Features
• 📦 Installation
• 🚀 Quick Start
• 📖 Usage Examples
  • Multi-Step Tour
  • Custom Styling
  • Blur & Gradient Effects
  • Automatic Scrolling
  • Callbacks
  • Custom Tooltip
  • Programmatic Control
• 🎨 API Reference
• 🎯 Best Practices
• 💡 Tips & Tricks
• 🐛 Troubleshooting
• 🤝 Contributing
• 📄 License
• 🙏 Credits
• 🔍 Keywords
• 📞 Support & Community

✨ Features

📦 Installation

🎯 Works with both Expo and React Native CLI!

✅ New Architecture Compatible - Fully supports React Native's new architecture (Fabric & TurboModules)

npm install @wrack/react-native-tour-guide react-native-svg

yarn add @wrack/react-native-tour-guide react-native-svg

pnpm add @wrack/react-native-tour-guide react-native-svg

npx expo install @wrack/react-native-tour-guide react-native-svg

Works seamlessly with Expo managed workflow. No additional configuration needed!

🎨 Optional Dependencies

💡 Pro Tip: The library works perfectly without these optional dependencies. Install them only if you want enhanced visual effects like blur and gradients.

npm install @react-native-community/blur

npm install react-native-linear-gradient

npm install @react-native-masked-view/masked-view

🚀 Quick Start

Get up and running in less than 1 minute!

Step 1: Wrap Your App

import {
  TourGuideProvider,
  TourGuideOverlay,
} from '@wrack/react-native-tour-guide';

export default function App() {
  return (
    <TourGuideProvider>
      <YourApp />
      <TourGuideOverlay />
    </TourGuideProvider>
  );
}

Step 2: Create Your First Tour

import React, { useRef, useEffect } from 'react';
import { View, Text, Pressable } from 'react-native';
import { useTourGuide } from '@wrack/react-native-tour-guide';

function WelcomeScreen() {
  const { startTour } = useTourGuide();
  const buttonRef = useRef(null);

  useEffect(() => {
    // Start the tour after the screen loads
    const timer = setTimeout(() => {
      startTour([
        {
          id: 'welcome',
          targetRef: buttonRef,
          title: 'Welcome! 👋',
          description:
            'This button does something amazing. Tap it to get started!',
          tooltipPosition: 'bottom',
          spotlightShape: 'rectangle',
        },
      ]);
    }, 500);

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

  return (
    <View>
      <Pressable ref={buttonRef}>
        <Text>Get Started</Text>
      </Pressable>
    </View>
  );
}

🎉 That's it! Your first tour is ready. Check out the Usage Examples below for more advanced features.

📖 Usage Examples

Multi-Step Tour

const step1Ref = useRef(null);
const step2Ref = useRef(null);
const step3Ref = useRef(null);

startTour([
  {
    id: 'step1',
    targetRef: step1Ref,
    title: 'Dashboard',
    description: 'View all your stats here.',
    tooltipPosition: 'bottom',
  },
  {
    id: 'step2',
    targetRef: step2Ref,
    title: 'Quick Actions',
    description: 'Access common tasks quickly.',
    tooltipPosition: 'top',
  },
  {
    id: 'step3',
    targetRef: step3Ref,
    title: 'Profile',
    description: 'Manage your account settings.',
    tooltipPosition: 'left',
  },
]);

Custom Styling

startTour(
  [
    {
      id: 'step1',
      targetRef: myRef,
      title: 'Custom Style',
      description: 'This tour has custom colors!',
    },
  ],
  {
    tooltipStyles: {
      backgroundColor: '#1E1E1E',
      titleColor: '#FFD700',
      descriptionColor: '#FFFFFF',
      primaryButtonColor: '#FFD700',
      borderRadius: 20,
    },
    spotlightStyles: {
      overlayOpacity: 0.8,
      overlayColor: '#000000',
    },
  }
);

With Blur and Gradient Effects

startTour(steps, {
  spotlightStyles: {
    enableBlur: true,
    blurAmount: 10,
    enableGradient: true,
    gradientColors: ['rgba(0,0,0,0)', 'rgba(0,0,0,0.8)'],
  },
});

Automatic Scrolling

const scrollViewRef = useRef(null);
const targetRef = useRef(null);
const [scrollY, setScrollY] = useState(0);

startTour([
  {
    id: 'scrollable',
    targetRef: targetRef,
    title: 'Scroll Target',
    description: 'The view will automatically scroll to show this element.',
    scrollToTarget: {
      scrollRef: scrollViewRef,
      offset: 50, // Extra padding
      animated: true,
      getCurrentScrollOffset: () => scrollY,
    },
  },
]);

With Callbacks

startTour([
  {
    id: 'step1',
    targetRef: myRef,
    title: 'First Step',
    description: 'This is the first step.',
    onNext: () => {
      console.log('Moving to next step');
      // Track analytics, update state, etc.
    },
    onPrev: () => {
      console.log('Going back');
    },
    onSkip: () => {
      console.log('Tour skipped');
      // Save that user skipped the tour
    },
  },
]);

Custom Tooltip Component

import { TooltipProps } from '@wrack/react-native-tour-guide';

const CustomTooltip = (props: TooltipProps) => {
  return (
    <View style={styles.customTooltip}>
      <Text style={styles.title}>{props.title}</Text>
      <Text style={styles.description}>{props.description}</Text>
      <Pressable onPress={props.onNext}>
        <Text>Continue →</Text>
      </Pressable>
    </View>
  );
};

startTour(steps, {
  renderTooltip: (props) => <CustomTooltip {...props} />,
});

Programmatic Control

const { startTour, nextStep, prevStep, skipTour, endTour, isActive } =
  useTourGuide();

// Start a tour
const handleStartTour = () => {
  startTour(steps);
};

// Control the tour programmatically
const handleManualNext = () => {
  nextStep();
};

const handleManualPrev = () => {
  prevStep();
};

const handleSkip = () => {
  skipTour();
};

const handleEnd = () => {
  endTour();
};

🎨 API Reference

useTourGuide()

Hook to access tour guide functionality.

Returns:

• startTour(steps, config?) - Start a tour with given steps and optional configuration
• nextStep() - Move to the next step
• prevStep() - Move to the previous step
• skipTour() - Skip the entire tour
• endTour() - End the tour programmatically
• isActive - Boolean indicating if a tour is currently active
• currentStep - Current step index (0-based)
• steps - Array of tour steps
• config - Current tour configuration

TourStep Interface

interface TourStep {
  id: string; // Unique identifier
  targetRef?: React.RefObject<any>; // Ref to the target component
  title: string; // Tooltip title
  description: string; // Tooltip description
  tooltipPosition?: 'top' | 'bottom' | 'left' | 'right';
  spotlightShape?: 'circle' | 'rectangle';
  spotlightPadding?: number; // Padding around spotlight (default: 8)
  spotlightBorderRadius?: number; // Border radius for rectangle (default: 12)
  scrollToTarget?: ScrollToTargetConfig;
  onNext?: () => void; // Callback when moving to next step
  onPrev?: () => void; // Callback when moving to previous step
  onSkip?: () => void; // Callback when skipping tour
}

TourGuideConfig Interface

interface TourGuideConfig {
  tooltipStyles?: {
    backgroundColor?: string;
    borderRadius?: number;
    titleColor?: string;
    descriptionColor?: string;
    buttonTextColor?: string;
    primaryButtonColor?: string;
    secondaryButtonColor?: string;
    skipButtonColor?: string;
    titleStyle?: TextStyle;
    descriptionStyle?: TextStyle;
    containerStyle?: ViewStyle;
  };
  spotlightStyles?: {
    overlayOpacity?: number; // 0-1 (default: 0.6)
    overlayColor?: string; // Default: 'black'
    blurAmount?: number; // 0-100 (default: 4)
    enableBlur?: boolean; // Default: false
    enableGradient?: boolean; // Default: false
    gradientColors?: string[];
  };
  showProgressDots?: boolean; // Default: false
  showStepCounter?: boolean; // Default: true
  enableBackButton?: boolean; // Default: true
  nextButtonText?: string; // Default: 'Next'
  prevButtonText?: string; // Default: 'Back'
  skipButtonText?: string; // Default: 'Skip'
  doneButtonText?: string; // Default: 'Done'
  renderTooltip?: (props: TooltipProps) => ReactNode;
  animationDuration?: number; // Default: 300ms
}

ScrollToTargetConfig Interface

interface ScrollToTargetConfig {
  scrollRef: React.RefObject<any>; // Reference to ScrollView
  offset?: number; // Additional offset (positive = down, negative = up)
  animated?: boolean; // Animate scroll (default: true)
  absolute?: boolean; // If true, offset is absolute position
  getCurrentScrollOffset?: () => number; // Function to get current scroll Y position
}

🎯 Best Practices

1. Timing: Start tours with a small delay (500-1000ms) to ensure layout is measured correctly
2. Persistence: Implement logic to show tours only once (use AsyncStorage or similar)
3. User Control: Always provide a "Skip" option for better UX
4. Keep It Short: Limit tours to 3-5 steps for better engagement
5. Contextual: Show tours when users first encounter a feature
6. Test Thoroughly: Test on different screen sizes and orientations

💡 Tips & Tricks

Persistent Tours

import AsyncStorage from '@react-native-async-storage/async-storage';

const TOUR_KEY = '@my_feature_tour_completed';

// Check if tour was already shown
const checkTourStatus = async () => {
  const hasSeenTour = await AsyncStorage.getItem(TOUR_KEY);
  if (!hasSeenTour) {
    startTour(steps);
  }
};

// Mark tour as completed
const completeTour = async () => {
  await AsyncStorage.setItem(TOUR_KEY, 'true');
};

// Use in onNext or onSkip callbacks
startTour([
  {
    // ... step config
    onNext: completeTour,
    onSkip: completeTour,
  },
]);

Measuring Components

For components that take time to render or animate, add a delay:

useEffect(() => {
  const timer = setTimeout(() => {
    startTour(steps);
  }, 1000); // Wait for animations/layouts

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

Handling Tab Bars

<Tab.Screen
  name="Profile"
  component={ProfileScreen}
  options={{
    tabBarButton: (props) => (
      <Pressable
        {...props}
        ref={tabButtonRef}
        style={props.style}
        onPress={props.onPress}
      />
    ),
  }}
/>

🐛 Troubleshooting

Tour Not Showing

1. Ensure TourGuideOverlay is placed after your main content
2. Check that the target ref is properly attached
3. Add a delay before starting the tour
4. Verify the component has a valid layout (not hidden or off-screen)

Highlight Position Wrong

1. Ensure target component is fully rendered before starting tour
2. Add delay before starting tour
3. Component must be visible on screen
4. Check for any transforms or absolute positioning

Tooltip Overlapping

• Adjust tooltipPosition prop
• Modify padding/offset in custom tooltip
• Use different spotlight shape

🤝 Contributing

We welcome contributions! Here's how you can help:

• 🐛 Report bugs
• 💡 Request features
• 📖 Improve documentation
• 🔧 Submit pull requests

Please read our Contributing Guide and Code of Conduct before submitting a PR.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits

Created with ❤️ by Himanshu Lal

Inspired by various React Native tour guide implementations and modern app onboarding patterns.

🔍 Keywords

react-native • react-native-tour-guide • tour-guide • walkthrough • onboarding • coach-marks • coachmarks • copilot • app-tour • user-guide • tutorial • spotlight • highlight • tooltip • feature-discovery • feature-tour • interactive-tour • guided-tour • app-walkthrough • user-onboarding • mobile-tour • react-native-walkthrough • react-native-onboarding • react-native-copilot • react-native-spotlight • react-native-coach-marks • react-native-tutorial • expo • expo-compatible • typescript • ios • android • cross-platform • new-architecture • fabric • turbomodules • svg-masking • animated • customizable • declarative • intro • hints • tips • product-tour • feature-hints • interactive-guide • step-by-step • user-education • app-intro • first-time-user-experience • ftue

📞 Support & Community

| Platform | Link | | -------------------- | ---------------------------------------------------------------------------------------------- | | 🐛 Bug Reports | GitHub Issues | | 💬 Discussions | GitHub Discussions | | 📧 Email | [email protected] | | 📖 Documentation | Usage Guide | | 📦 NPM Package | @wrack/react-native-tour-guide |