📘 react-native-tuto-showcase

🔦 A fully customizable Spotlight / Tutorial / Coachmark overlay for React Native

Perfect for onboarding flows, feature tours, highlighting UI elements, and guiding users interactively.

Now with full-screen Lottie placement + custom offsets.

✨ Features

• 🎯 Highlight any UI element with Circle / RoundRect spotlight

• 📐 Auto-calculated spotlight position using measureInWindow

• 🔁 Show-once logic (AsyncStorage)

• 🎞 Lottie Animations with full-screen positioning

  • top-left, top-right, top-center
  • bottom-left, bottom-right, bottom-center
  • center
  • • lottieOffset={{dx, dy}}

• 📦 Multiple spots on one screen

• ✋ Gesture hints (swipe / scroll)

• 🎨 Fully customizable:

  • Colors
  • Button style
  • Fonts
  • Overlay background

• 📱 Works on iOS & Android

• ⚡ Supports React Native 0.72+

📦 Installation

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

🚀 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={
          'يمكنك سحب هذا القسم لأعلى أو لأسفل لتغيير ترتيبه.\n' +
          'سيتم حفظ الترتيب تلقائيًا.'
        }
        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 (New)

The Lottie animation is now 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

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

🧩 Props

<TutoShowcase />

| Prop | Type | Default | Description | | ------------------------ | ------------------------------ | ------------------ | ----------------------- | | title | ReactNode | — | Title JSX | | description | string \| ReactNode | — | Description text | | buttonText | string | "GOT IT" | CTA label | | buttonTextStyle | TextStyle | — | Style for CTA text | | buttonContainerStyle | ViewStyle | — | Style for CTA button | | overlayBackgroundColor | string | rgba(0,0,0,0.78) | Dim overlay color | | onGotIt | () => void | — | Called when CTA pressed | | lottie | ReactElement | — | Lottie animation | | lottiePlacement | "top-left" \| ... | "top-center" | ⭐ Full-screen placement | | lottieOffset | { dx?: number; dy?: number } | {} | Extra offset |

🎛 Ref API

const tutoRef = useRef<TutoShowcaseHandle>(null);

| Method | Description | | -------------------------------------- | ----------------------------- | | on(ref) | Select target element | | addCircle(ratio?) | Add circle spotlight | | addRoundRect(ratio?, radius?, opts?) | Add rounded spotlight | | withBorder() | Add border | | displaySwipableLeft() | Gesture hint | | displaySwipableRight() | Gesture hint | | displayScrollable() | Gesture hint | | onClick(cb) | Capture taps inside spotlight | | show() | Show spotlight immediately | | showOnce(key) | Show once (AsyncStorage) | | resetShowOnce(key) | Clear stored key | | isShowOnce(key) | Check if key shown |

🗂 Show Once Logic

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

🎨 Button Customization

<TutoShowcase
  buttonContainerStyle={{
    backgroundColor: '#FFD700',
    borderRadius: 10,
  }}
  buttonTextStyle={{
    color: '#000',
    fontWeight: 'bold',
  }}
/>

📐 Spotlight Options

Circle

.on(ref)
.addCircle(1.3)
.show()

Rounded Rectangle

.on(ref)
.addRoundRect(1.1, 20, { pad: 30 })
.show()

🎥 Demo Videos

📱 iOS

https://github.com/ahmedhegazydev/react-native-tuto-showcase/blob/master/src/assets/SimulatorScreenRecording-iPhone16Pro-2025-11-24at14.14.46online-video-cutter.com-ezgif.com-video-to-gif-converter.gif

🤖 Android

https://github.com/ahmedhegazydev/react-native-tuto-showcase/blob/master/src/assets/ScreenRecording2025-12-02at7.52.23PMonline-video-cutter.com-ezgif.com-video-to-gif-converter.gif

📝 License

MIT © Ahmed Mohamed Ali Ali Hegazy