Description:
React Native Onboarding Flow is a component library for creating modal-based onboarding experiences within Expo React Native applications.
It provides a structured way to guide new users through your app’s features using a sequence of customizable slides.
You can use a combination of images and videos to make the introduction engaging.
It also includes built-in animations, progress indicators, and the option to integrate a custom paywall screen after the final slide.
Features
- 🎠Presents the onboarding experience inside a modal for a clean user interface.
- 🎨 Includes built-in fade, slide, and scale animations for dynamic slide transitions.
- 🎥 Supports both local images and MP4 videos as media for each slide.
- 📱 Developed with full TypeScript support for improved code quality and safety.
- 🎯 Built with minimal dependencies to keep your application’s bundle size small.
- 🎪 Offers extensive customization options for themes, colors, and component behavior.
- 📊 Displays progress dots to show users their position in the onboarding sequence.
- 🔒 Gives you control over whether users can close the onboarding flow before completion.
- 💰 Includes support for displaying a custom paywall component after the last slide.
Preview
Use Cases
- First-Time User Introduction. Guide new users through the main features and functionalities of your application to improve initial engagement.
- Feature Discovery. Highlight new or existing features that users might not be aware of to increase adoption.
- Permission Priming. Explain why your app requires certain permissions before the official system prompt appears, which can increase acceptance rates.
- Subscription Upsell. Present a paywall or subscription screen immediately after the onboarding tour to convert users to a premium plan.
How to Use It
1. To get started, you need to install the package and its peer dependency, expo-av, which handles video playback. You can use either npm or yarn.
npm install react-native-onboarding-flow expo-avOr if you use yarn.
yarn add react-native-onboarding-flow expo-av2. Import the OnboardingFlow component. You manage its visibility with a state variable and define the content for each screen in a slides array.
import React, { useState } from 'react';
import { View } from 'react-native';
import { OnboardingFlow } from 'react-native-onboarding-flow';
export default function App() {
const [isOnboardingVisible, setOnboardingVisible] = useState(true);
const onboardingSlides = [
{
id: 'slide1',
media: {
type: 'image',
source: require('./assets/feature-image.png'),
width: 250,
height: 250,
},
title: 'Explore Key Features',
description: 'Learn about the core functionalities.',
animation: 'fadeIn',
},
{
id: 'slide2',
media: {
type: 'video',
source: require('./assets/tutorial-video.mp4'),
autoPlay: true,
loop: true,
},
title: 'Watch a Quick Tutorial',
description: 'See the app in action with a short video.',
animation: 'slideUp',
},
];
return (
<View style={{ flex: 1 }}>
{/* Your main app content goes here */}
<OnboardingFlow
slides={onboardingSlides}
visible={isOnboardingVisible}
onComplete={() => setOnboardingVisible(false)}
showProgress={true}
closeable={false}
/>
</View>
);
}3. The component supports showing a custom component after the last slide, which is useful for paywalls. You can enable this feature by setting the showPaywall prop to true and passing your custom component to the paywallComponent prop.
Your paywall component receives an onComplete function as a prop. You must call this function to close the entire onboarding modal.
import React, { useState } from 'react';
import { View, Text, Button } from 'react-native';
import { OnboardingFlow } from 'react-native-onboarding-flow';
// Define your custom paywall component
const CustomPaywall = ({ onComplete }) => (
<View style={{ flex: 1, justifyContent: 'center', padding: 20 }}>
<Text style={{ fontSize: 22, textAlign: 'center' }}>Unlock Premium Access</Text>
<Button title="Start 7-Day Trial" onPress={onComplete} />
</View>
);
export default function App() {
const [isOnboardingVisible, setOnboardingVisible] = useState(true);
// Your slides array
const onboardingSlides = [ /* ... slides data ... */ ];
return (
<View style={{ flex: 1 }}>
<OnboardingFlow
slides={onboardingSlides}
visible={isOnboardingVisible}
onComplete={() => setOnboardingVisible(false)}
showPaywall={true}
paywallComponent={<CustomPaywall />}
/>
</View>
);
}4. Customize the appearance of the onboarding modal by passing a theme object. This object allows you to define colors for the background, text, buttons, and progress dots.
import React, { useState } from 'react';
import { View } from 'react-native';
import { OnboardingFlow } from 'react-native-onboarding-flow';
export default function App() {
const [isOnboardingVisible, setOnboardingVisible] = useState(true);
// Your slides array
const onboardingSlides = [ /* ... slides data ... */ ];
const customTheme = {
backgroundColor: '#0D1117',
titleColor: '#C9D1D9',
descriptionColor: '#8B949E',
buttonBackgroundColor: '#238636',
buttonTextColor: '#FFFFFF',
progressDotColor: '#21262D',
progressDotActiveColor: '#238636',
closeButtonColor: '#8B949E',
};
return (
<View style={{ flex: 1 }}>
<OnboardingFlow
slides={onboardingSlides}
visible={isOnboardingVisible}
onComplete={() => setOnboardingVisible(false)}
theme={customTheme}
/>
</View>
);
}5. Available OnboardingFlow Props
slides: (Required) An array of objects where each object defines the content and appearance of a single slide.visible: (Required) A boolean that controls whether the onboarding modal is currently visible or hidden.onComplete: (Required) A function that is called when the user finishes the last slide or closes the flow.closeable: A boolean that determines if a close button is shown, allowing users to exit the flow before completion. Defaults tofalse.showProgress: A boolean that toggles the visibility of the progress dots at the bottom of the modal. Defaults totrue.theme: An object used to provide custom colors for the modal’s background, text, and buttons.showPaywall: A boolean that, whentrue, displays a custom component after the final slide. Defaults tofalse.paywallComponent: The custom React component to render as the paywall whenshowPaywallistrue.
6. Available Slide Data Structure
id: A unique string identifier for the slide.title: The main heading text for the slide.description: The smaller descriptive text that appears below the title.animation: An optional string that specifies the entry animation for the slide. Can be'fadeIn','slideUp', or'scaleIn'.media: An object that defines the visual content for the slide. It contains the following properties:type: (Required) A string specifying the media type, either'image'or'video'.source: (Required) The local asset for the image or video, loaded usingrequire().autoPlay: For videos, a boolean to control if the video starts playing automatically. Defaults totrue.loop: For videos, a boolean that makes the video repeat continuously. Defaults totrue.muted: For videos, a boolean to control if the video plays with sound. Defaults totrue.width: An optional number to set a custom width for the media.height: An optional number to set a custom height for the media.borderRadius: An optional number to apply a border radius to the media container.
FAQs
Q: Can this library be used in a standard React Native project without Expo?
A: This library is specifically built for Expo React Native projects because it relies on expo-av for video support.
Q: Is it possible to use remote URLs for images or videos?
A: The source property in the media object expects a local asset loaded via require(). It does not support remote URLs for media files.
Q: Can a user skip the onboarding flow?
A: Yes, you can allow users to skip the flow by setting the closeable prop to true. This will display a close button on the modal.
