Highlights a UI element with a spotlight cutout, shows a tooltip with title and description, and guides the user step-by-step through any screen tab.

Preview

Features

• Spotlight cutout — rect or circle shape with configurable padding
• Auto-scroll to the target element inside a ScrollView
• tapHint mode — overlay shows a pulsing hand icon instead of a tooltip; the next step is triggered by resumeAfterTap()
• Per-tab tours with automatic "already shown" persistence via a pluggable storage adapter
• alwaysShow flag for development
• Animated transitions between steps (fade / scale)
• Zero native modules — pure React Native

Installation

# npm
npm install lp-coachmark

# yarn
yarn add lp-coachmark

Peer dependencies

| Package | Version | |---|---| | react | ≥ 18.0.0 | | react-native | ≥ 0.73.0 | | expo-router | ≥ 3.0.0 |

Quick start

1. Wrap your app with CoachmarkProvider

// app/_layout.tsx
import { CoachmarkProvider } from 'lp-coachmark';
import { useSafeAreaInsets } from 'react-native-safe-area-context';
import AsyncStorage from '@react-native-async-storage/async-storage';

export default function RootLayout() {
  const insets = useSafeAreaInsets();
  return (
    <CoachmarkProvider
      tabBarHeight={84}
      safeAreaTop={insets.top}
      storage={{
        get: AsyncStorage.getItem,
        set: AsyncStorage.setItem,
      }}
    >
      {/* ... */}
    </CoachmarkProvider>
  );
}

2. Register steps inside a screen

// app/(tabs)/home.tsx
import { useRef } from 'react';
import { View, Text } from 'react-native';
import { useCoachmarkStep, useTabCoachmark } from 'lp-coachmark';

export default function HomeScreen() {
  // Start the tour automatically when the tab gains focus
  useTabCoachmark('home');

  const buttonRef = useCoachmarkStep({
    key: 'home-button',
    tabKey: 'home',
    title: 'Create something new',
    description: 'Tap this button to create your first item.',
  });

  return (
    <View>
      <View ref={buttonRef}>
        <Text>+ New</Text>
      </View>
    </View>
  );
}

3. Trigger the tour manually (optional)

import { useCoachmark } from 'lp-coachmark';

const { start } = useCoachmark();

// start tour for "home" tab from step 0
start('home', 0, () => console.log('tour finished'));

How it works

1. Each component that should be highlighted calls useCoachmarkStep(), which returns a ref to attach to a View. The hook registers the step in the global context.
2. useTabCoachmark(tabKey) listens to useFocusEffect — when the tab is focused it checks storage, and if the tour was not yet shown, calls start(tabKey) after a short delay.
3. CoachmarkOverlay renders a Modal on top of everything. It measures the target View with measureInWindow, draws the spotlight mask around it, and shows a tooltip.
4. The user taps Next / Back / Skip to navigate or dismiss. On the last step "Done" calls onFinish, which saves the "done" flag to storage.

API overview

| Export | Type | Description | |---|---|---| | CoachmarkProvider | Component | Root context provider | | useCoachmark | Hook | Access context (start, resumeAfterTap, etc.) | | useCoachmarkStep | Hook | Register a single step and get a ref | | useTabCoachmark | Hook | Auto-start tour on tab focus |

See the full documentation for the complete prop / option reference and real-world usage patterns.

License

MIT