✨ Features

• 🎨 Multiple shapes - Circle, rounded rectangle, and pill shapes
• 📱 Smart positioning - Auto-placement with boundary detection
• 🔄 Auto-scroll - Automatically scroll to off-screen elements
• ♿️ Accessible - Screen reader support and reduced motion
• 💾 Show once - Built-in persistence (never annoy users twice)
• 🎭 Themeable - Light/dark modes and custom styling
• 🔧 Custom tooltips - Full control with render props
• 🎯 Lifecycle hooks - onEnter, onExit, onBeforeEnter, onBeforeScroll
• ⚡️ Performant - No screenshots, pure vector masking
• 📦 TypeScript - Full type safety included
• 🌐 Cross-platform - iOS, Android, and Web

📦 Installation

npm install @edwardloopez/react-native-coachmark react-native-svg react-native-reanimated

Required Dependencies

This library depends on:

• react-native-svg (≥13.0.0) - For vector graphics
• react-native-reanimated (≥3.0.0) - For smooth animations

Note: Follow the Reanimated installation guide to configure the Babel plugin.

Optional: Persistence

For "show once" functionality, install one of these:

# AsyncStorage (most common)
npm install @react-native-async-storage/async-storage

# OR MMKV (faster, recommended)
npm install react-native-mmkv

🚀 Quick Start

Step 1: Setup Provider

Wrap your app with the provider and add the overlay:

import { CoachmarkProvider, CoachmarkOverlay } from '@edwardloopez/react-native-coachmark';

export default function App() {
  return (
    <CoachmarkProvider>
      <YourApp />
      <CoachmarkOverlay />
    </CoachmarkProvider>
  );
}

Step 2: Mark UI Elements

Wrap elements you want to highlight:

import { CoachmarkAnchor } from '@edwardloopez/react-native-coachmark';

<CoachmarkAnchor id="create-button" shape="circle">
  <Button title="Create" onPress={handleCreate} />
</CoachmarkAnchor>

<CoachmarkAnchor id="filters" shape="rect">
  <View style={styles.filters}>
    <Text>Filters</Text>
  </View>
</CoachmarkAnchor>

Step 3: Create and Start Tour

import { useCoachmark, createTour } from '@edwardloopez/react-native-coachmark';

function HomeScreen() {
  const { start } = useCoachmark();

  const startTour = () => {
    start(
      createTour('onboarding', [
        {
          id: 'create-button',
          title: 'Create New Item',
          description: 'Tap here to add a new item',
          placement: 'bottom',
        },
        {
          id: 'filters',
          title: 'Filter Results',
          description: 'Use these to narrow your search',
          placement: 'top',
        },
      ], {
        showOnce: true,  // Show only once per user
        delay: 500,      // Wait 500ms before starting
      })
    );
  };

  return <Button title="Start Tour" onPress={startTour} />;
}

📖 API Reference

Core Components

<CoachmarkProvider>

Root provider that manages tour state.

<CoachmarkProvider theme={customTheme} storage={storageAdapter}>
  {children}
</CoachmarkProvider>

<CoachmarkOverlay>

Renders the spotlight and tooltip. Add once at app root.

<CoachmarkAnchor>

Marks elements for highlighting.

<CoachmarkAnchor
  id="button-id"     // Required: Unique identifier
  shape="circle"     // 'circle' | 'rect' | 'pill'
  padding={12}       // Space around element (pixels)
  radius={8}         // Corner radius for rect/pill
  scrollRef={scrollViewRef}  // For auto-scroll feature
>
  {children}
</CoachmarkAnchor>

Props:

| Prop | Type | Description | |------|------|-------------| | id | string (required) | Unique identifier for this anchor | | shape | 'circle' \| 'rect' \| 'pill' | Spotlight shape (overrides step config) | | padding | number | Extra space around element (pixels) | | radius | number | Corner radius for rounded shapes (pixels) | | scrollRef | React.Ref | Ref to parent ScrollView/FlatList (required for autoFocus) |

Hook

useCoachmark()

Control tours programmatically.

const { start, next, back, skip, stop, state } = useCoachmark();

// Start a tour
start(tour);

// Navigate
next();   // Next step
back();   // Previous step
skip();   // End tour

// Check state
state.isActive   // Is tour running?
state.index      // Current step (0-based)

Functions

createTour(key, steps, options)

Create a tour configuration.

const tour = createTour(
  'my-tour',                    // Unique identifier
  [
    {
      id: 'anchor-id',          // Anchor to highlight
      title: 'Title',           // Tooltip title
      description: 'Info',      // Tooltip description
      placement: 'bottom',      // Tooltip position
      shape: 'circle',          // Spotlight shape
    },
  ],
  {
    showOnce: true,             // Show only once
    delay: 500,                 // Start delay (ms)
  }
);

Step Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | id | string | required | Anchor ID to highlight | | title | string | - | Tooltip title text | | description | string | - | Tooltip description text | | placement | 'top' \| 'bottom' \| 'left' \| 'right' \| 'auto' | 'auto' | Tooltip position | | shape | 'circle' \| 'rect' \| 'pill' | - | Spotlight shape | | padding | number | - | Space around highlight (pixels) | | radius | number | - | Corner radius for rect/pill shapes (pixels) | | autoFocus | 'always' \| 'ifNeeded' | - | Auto-scroll behavior | | scrollBehavior | 'smooth' \| 'instant' | - | Scroll animation | | scrollPadding | number | 20 | Space from screen edges when scrolling (pixels) | | scrollDelay | number | 150 | Delay after scroll before showing tooltip (ms) | | onBeforeEnter | async function | - | Callback before step starts (return false to skip) | | onBeforeScroll | async function | - | Callback before auto-scrolling starts | | onEnter | function | - | Callback when step becomes active | | onExit | function | - | Callback when leaving step | | renderTooltip | React.ComponentType | - | Custom tooltip component for this step |

Tour Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | showOnce | boolean | false | Show tour only once (requires storage) | | delay | number | 0 | Delay before tour starts (milliseconds) | | renderTooltip | React.ComponentType | - | Global custom tooltip renderer for all steps |

🚀 Try it now

📚 Next Steps

Explore advanced features and best practices:

Learn More

• 🔧 Advanced Usage - Auto-scroll, lifecycle hooks, custom themes, plugins
• 💡 Examples - Real-world use cases and complete code samples
• ♿️ Accessibility - Make tours inclusive for all users
• ✅ Best Practices - Design, performance, and testing guidelines

Resources

• 🔗 NPM Package
• 🐛 Report Issues
• 💬 Discussions

🌟 Showcase

Using this library? Open a PR to add your app here!

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Made with ❤️ for the React Native community