React Native Onboarding Flow

Beautiful, customizable onboarding flows for Expo React Native apps with smooth animations and video support.

Features ✨

• 🎭 Modal-based - Non-intrusive onboarding experience
• 🎨 Beautiful animations - Fade, slide, and scale effects
• 🎥 Image & Video support - Use images or MP4 videos
• 📱 TypeScript first - Full type safety
• 🎯 Minimal dependencies - Only expo-av for videos
• 📱 Expo compatible - Designed for Expo React Native projects
• 🎪 Highly customizable - Control every aspect
• 📊 Progress indicators - Visual progress dots
• 🔒 Closeable control - Prevent/allow closing
• 💰 Paywall support - Display custom paywall after onboarding

Demo

demo-package.mp4

Requirements

• Expo React Native app (uses expo-av for video support)
• React Native >= 0.60.0
• Expo SDK >= 49.0.0

Installation

Install the package along with its peer dependency:

npm install react-native-onboarding-flow expo-av
# or
yarn add react-native-onboarding-flow expo-av

Why install expo-av? It's a peer dependency needed for video playback. This prevents version conflicts and keeps your bundle size optimized.

Basic Usage

import React, { useState } from 'react';
import { OnboardingFlow } from 'react-native-onboarding-flow';

const App = () => {
  const [showOnboarding, setShowOnboarding] = useState(true);

  const slides = [
    {
      id: 'welcome',
      media: {
        type: 'video',
        source: require('./assets/welcome-video.mp4'),
        autoPlay: true,
        loop: true,
        muted: true,
      },
      title: 'Welcome to Our App',
      description: 'Experience the future of mobile apps',
      animation: 'scaleIn',
    },
    {
      id: 'features',
      media: {
        type: 'image',
        source: require('./assets/features.png'),
        width: 300,
        height: 200,
        borderRadius: 20,
      },
      title: 'Powerful Features',
      description: 'Everything you need in one place',
      animation: 'fadeIn',
    },
  ];

  return (
    <OnboardingFlow
      slides={slides}
      visible={showOnboarding}
      onComplete={() => setShowOnboarding(false)}
      closeable={false}
      showProgress={true}
    />
  );
};

Paywall Integration

Display a custom paywall component after the onboarding completes:

import React, { useState } from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { OnboardingFlow } from 'react-native-onboarding-flow';

const MyPaywall = ({ onComplete }) => (
  <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center', padding: 20 }}>
    <Text style={{ fontSize: 24, fontWeight: 'bold', marginBottom: 20 }}>
      Unlock Premium Features
    </Text>
    <Text style={{ fontSize: 16, textAlign: 'center', marginBottom: 30 }}>
      Get access to all features with our premium subscription
    </Text>
    <TouchableOpacity
      style={{ backgroundColor: '#007AFF', padding: 15, borderRadius: 25 }}
      onPress={onComplete} // This will close the onboarding flow
    >
      <Text style={{ color: 'white', fontSize: 16 }}>Start Free Trial</Text>
    </TouchableOpacity>
  </View>
);

const App = () => {
  const [showOnboarding, setShowOnboarding] = useState(true);

  return (
    <OnboardingFlow
      slides={slides}
      visible={showOnboarding}
      onComplete={() => setShowOnboarding(false)}
      showPaywall={true}
      paywallComponent={<MyPaywall />}
    />
  );
};

Custom Theme

const App = () => {
  const [showOnboarding, setShowOnboarding] = useState(true);

  // Custom theme colors
  const theme = {
    backgroundColor: '#1a1a1a',
    titleColor: '#ffffff',
    descriptionColor: '#cccccc',
    buttonBackgroundColor: '#007AFF',
    buttonTextColor: '#ffffff',
    progressDotColor: '#333333',
    progressDotActiveColor: '#007AFF',
    closeButtonColor: '#cccccc',
  };

  return (
    <OnboardingFlow
      slides={slides}
      visible={showOnboarding}
      onComplete={() => setShowOnboarding(false)}
      theme={theme}
    />
  );
};

API Reference

OnboardingFlow Props

Prop	Type	Default	Description
slides	OnboardingSlideData[]	required	Array of slide data
visible	boolean	required	Controls modal visibility
onComplete	() => void	required	Called when onboarding completes
closeable	boolean	false	Allow users to close before completion
showProgress	boolean	true	Show progress dots
theme	OnboardingTheme	undefined	Custom colors
showPaywall	boolean	false	Show paywall after last slide
paywallComponent	React.ReactNode	undefined	Custom paywall component

Slide Data Structure

interface OnboardingSlideData {
  id: string;
  media: {
    type: 'image' | 'video';
    source: any; // require() asset
    autoPlay?: boolean; // For videos (default: true)
    loop?: boolean; // For videos (default: true)  
    muted?: boolean; // For videos (default: true)
    width?: number; // Custom width in pixels
    height?: number; // Custom height in pixels
    borderRadius?: number; // Custom border radius in pixels
  };
  title: string;
  description: string;
  animation?: 'fadeIn' | 'slideUp' | 'scaleIn';
}

Media Configuration

Option	Type	Default	Description
type	'image' | 'video'	required	Media type
source	any	required	Asset source (require())
autoPlay	boolean	true	Auto-play videos when slide becomes active
loop	boolean	true	Loop videos continuously
muted	boolean	true	Start videos muted
width	number	screenWidth * 0.6	Custom width in pixels (default: 60% of screen width)
height	number	screenWidth * 0.6	Custom height in pixels (default: 60% of screen width)
borderRadius	number	12 (videos), undefined (images)	Border radius in pixels

Theme Colors

Option	Type	Default	Description
backgroundColor	string	'white'	Modal background color
titleColor	string	'#2F4F2F'	Title text color
descriptionColor	string	'#666'	Description text color
buttonBackgroundColor	string	'#6B8E5A'	Next button background
buttonTextColor	string	'white'	Next button text color
progressDotColor	string	'#E5E5E5'	Inactive dot color
progressDotActiveColor	string	'#6B8E5A'	Active dot color
closeButtonColor	string	'#666'	Close button icon color

Animation Types

• fadeIn - Gentle fade in effect
• slideUp - Slide up from bottom
• scaleIn - Scale in with spring animation

License

MIT © Binb1