🔦 react-native-tuto-showcase

Fully Customizable Spotlight / Tutorial / Coachmark Overlay for React Native — Perfect for Onboarding, Feature Discovery & Guided Tours

A lightweight yet powerful spotlight / walkthrough / coachmark component for React Native that helps you:

• Guide users through onboarding flows
• Highlight new features
• Explain complex UI
• Drive feature adoption & discovery

Now with full-screen Lottie placement, custom offsets, and smart tooltips.

✨ Features

• 🎯 Highlight any UI element

  • Circle or rounded-rectangle spotlight
  • Uses measureInWindow to auto-calc coordinates

• 📐 Smart positioning

  • Spotlight automatically tracks the referenced ref

• 🧠 Show-once logic (AsyncStorage)

  • .showOnce(key) / .resetShowOnce(key) / .isShowOnce(key)

• 🎞 Lottie Animations — Full-Screen Placement

  • Place the animation relative to the screen, not the spotlight

  • Built-in placements:

    • top-left, top-center, top-right
    • bottom-left, bottom-center, bottom-right
    • center

  • Fine-tune with lottieOffset={{ dx, dy }}

• 💬 Tooltips (Coachmark Bubble) — NEW

  • Custom tooltip bubble near the spotlight target
  • Smart placement: auto | above | below
  • RTL-aware arrow positioning (left | center)
  • Custom arrow inset & spacing
  • Fully customizable background & layout

• 📦 Multiple spots on one screen

  • Chain calls on the same ref (circle / rect / gestures)

• ✋ Gesture hints

  • .displaySwipableLeft()
  • .displaySwipableRight()
  • .displayScrollable()

• 🎨 Fully customizable UI

  • Overlay color
  • Button container & text style
  • Custom title / description JSX
  • Optional tooltip bubble

• 📱 Cross-platform

  • iOS & Android

• ⚡ Modern RN stack

  • React Native 0.72+
  • TypeScript-friendly API

📦 Installation

npm install react-native-tuto-showcase
# OR
yarn add react-native-tuto-showcase

No extra native setup required.

🚀 Basic Usage

import React, { useRef } from 'react';
import { View, Text, Pressable } from 'react-native';
import TutoShowcase, { TutoShowcaseHandle } from 'react-native-tuto-showcase';

export default function Home() {
  const tutoRef = useRef<TutoShowcaseHandle>(null);
  const boxRef = useRef<View>(null);

  return (
    <>
      <TutoShowcase
        ref={tutoRef}
        title={<Text style={{ color: '#fff', fontSize: 22 }}>ترتيب الأقسام</Text>}
        description="يمكنك سحب هذا القسم لأعلى أو لأسفل لتغيير ترتيبه."
        buttonText="تمام"
      />

      <View
        ref={boxRef}
        style={{ marginTop: 120, padding: 20, backgroundColor: '#eee' }}
      >
        <Text>Drag Me</Text>
      </View>

      <Pressable
        onPress={() =>
          tutoRef.current
            ?.on(boxRef)
            .addRoundRect()
            .withBorder()
            .showOnce('highlight-box')
        }
      >
        <Text>Start Tutorial</Text>
      </Pressable>
    </>
  );
}

🎞 Lottie Placement

The Lottie animation is positioned relative to the full screen, not the spotlight.

Available placements

top-left
top-center
top-right
bottom-left
bottom-center
bottom-right
center

Example

import LottieView from 'lottie-react-native';

<TutoShowcase
  ref={tutoRef}
  lottie={
    <LottieView
      source={require('./hand.json')}
      style={{ width: 120, height: 120 }}
      autoPlay
      loop
    />
  }
  lottiePlacement="top-right"
  lottieOffset={{ dx: -20, dy: 10 }}
/>

💬 Tooltip (New)

Render a custom tooltip bubble near the highlighted target instead of the default title/description section.

Example

<TutoShowcase
  ref={tutoRef}
  tooltip={
    <Text style={{ color: '#fff', fontSize: 16, lineHeight: 22 }}>
      Tap here to open your profile settings
    </Text>
  }
  tooltipPlacement="auto"
  tooltipArrowSide="left"
  tooltipArrowInset={24}
  tooltipGap={14}
  tooltipBackgroundColor="#3B3563"
/>

Notes

• When tooltip is provided, the default title / description section will not render.
• Tooltip placement is calculated based on the first spotlight target.
• Tooltip arrow automatically flips based on placement (above / below).
• Fully RTL-aware.

🧩 <TutoShowcase /> Props

| Prop | Type | Default | Description | | ------------------------ | ------------------------------ | ------------------ | ------------------- | | title | ReactNode | — | Title JSX | | description | string \| ReactNode | — | Description content | | buttonText | string | "GOT IT" | CTA label | | buttonTextStyle | TextStyle | — | CTA text style | | buttonContainerStyle | ViewStyle | — | CTA container style | | overlayBackgroundColor | string | rgba(0,0,0,0.78) | Overlay color | | onGotIt | () => void | — | CTA callback | | lottie | ReactElement | — | Lottie animation | | lottiePlacement | Placement | "top-center" | Lottie position | | lottieOffset | { dx?: number; dy?: number } | {} | Lottie offset | | tooltip | ReactNode | — | Tooltip content | | tooltipOffset | { dx?: number; dy?: number } | {} | Tooltip offset | | tooltipPlacement | "auto" \| "above" \| "below" | "auto" | Tooltip placement | | tooltipArrowSide | "left" \| "center" | "left" | Arrow alignment | | tooltipArrowInset | number | 24 | Arrow inset | | tooltipGap | number | 14 | Gap from target | | tooltipArrowGap | number | 6 | Extra arrow gap | | tooltipEdgePadding | number | 12 | Screen edge padding | | tooltipBackgroundColor | string | #3B3563 | Tooltip background |

🎛 Ref API

const tutoRef = useRef<TutoShowcaseHandle>(null);

| Method | Description | | -------------------------------------- | -------------------------- | | on(ref) | Attach spotlight to target | | addCircle(ratio?) | Circular spotlight | | addRoundRect(ratio?, radius?, opts?) | Rounded rectangle | | withBorder() | Border around spotlight | | displaySwipableLeft() | Swipe-left hint | | displaySwipableRight() | Swipe-right hint | | displayScrollable() | Scroll hint | | onClick(cb) | Capture clicks | | show() | Show immediately | | showOnce(key) | Show once only | | resetShowOnce(key) | Reset key | | isShowOnce(key) | Check key |

🗂 Show Once Logic

tutoRef.current
  ?.on(boxRef)
  .addCircle()
  .showOnce('first-time-highlight');

Reset:

tutoRef.current?.resetShowOnce('first-time-highlight');

🧠 Typical Use Cases

• App onboarding
• Feature discovery
• Coachmarks
• Dashboards & settings
• Drag & drop education
• UX testing

🗺 Roadmap

• ✅ Tooltips
• ✅ Lottie full-screen placement
• 🔜 Multi-step sequences
• 🔜 Built-in themes
• 🔜 Next / Previous navigation
• 🔜 Expo examples

👤 Author

Built with ❤️ by Ahmed Hegazy

• 📧 [email protected]
• 🐙 GitHub: @ahmedhegazydev

📄 License

MIT © Ahmed Mohamed Ali Ali Hegazy