@umituz/react-native-onboarding

Advanced onboarding flow for React Native apps with personalization questions, gradient backgrounds, animations, and customizable slides. Built with SOLID, DRY, KISS principles.

✨ Features

• 🎨 Beautiful gradient backgrounds with smooth transitions
• ❓ Personalization questions - Get to know your users
• 📝 Multiple question types - Single choice, multiple choice, text input, slider, rating
• ✅ Built-in validation - Required fields, min/max values, custom validators
• 🔄 Conditional slides - Skip slides based on previous answers
• 💾 Persistent storage - Save user answers and onboarding state
• 🎯 Type-safe - Full TypeScript support
• 🎭 Customizable - Custom header, footer, and slide components
• 📱 Universal - Works on iOS, Android, and Web
• 🚀 Production-ready - Used in hundreds of apps

📦 Installation

npm install @umituz/react-native-onboarding

Peer Dependencies

npm install \
  @umituz/react-native-storage \
  @umituz/react-native-localization \
  @umituz/react-native-design-system-theme \
  @umituz/react-native-design-system \
  @umituz/react-native-design-system-atoms \
  @react-native-community/slider \
  expo-linear-gradient \
  react-native-safe-area-context \
  zustand

🚀 Quick Start

Basic Onboarding (Info Slides Only)

import { OnboardingScreen } from '@umituz/react-native-onboarding';

const slides = [
  {
    id: '1',
    title: 'Welcome to Our App',
    description: 'Discover amazing features',
    icon: '👋',
    gradient: ['#667eea', '#764ba2'],
  },
  {
    id: '2',
    title: 'Stay Organized',
    description: 'Keep track of everything',
    icon: '📋',
    gradient: ['#f093fb', '#f5576c'],
  },
];

<OnboardingScreen
  slides={slides}
  onComplete={() => console.log('Onboarding completed')}
/>

Advanced Onboarding (With Personalization Questions)

import { OnboardingScreen, OnboardingSlide } from '@umituz/react-native-onboarding';

const slides: OnboardingSlide[] = [
  // Welcome slide
  {
    id: '1',
    type: 'welcome',
    title: 'Welcome to FishWise',
    description: 'Your personal aquarium assistant',
    icon: '🐠',
    gradient: ['#667eea', '#764ba2'],
  },
  
  // Question: Experience level
  {
    id: '2',
    type: 'question',
    title: 'What\'s your experience level?',
    description: 'Help us personalize your experience',
    icon: '🎯',
    gradient: ['#f093fb', '#f5576c'],
    question: {
      id: 'experience_level',
      type: 'single_choice',
      question: 'Select your experience level',
      storageKey: '@user_experience_level',
      validation: { required: true },
      options: [
        { id: 'beginner', label: 'Beginner', icon: '🌱' },
        { id: 'intermediate', label: 'Intermediate', icon: '🌿' },
        { id: 'expert', label: 'Expert', icon: '🌳' },
      ],
    },
  },
  
  // Question: Tank size
  {
    id: '3',
    type: 'question',
    title: 'What\'s your tank size?',
    description: 'This helps us recommend suitable fish',
    icon: '📏',
    gradient: ['#4facfe', '#00f2fe'],
    question: {
      id: 'tank_size',
      type: 'slider',
      question: 'Select your tank size (gallons)',
      storageKey: '@user_tank_size',
      validation: { required: true, min: 10, max: 500 },
      defaultValue: 50,
    },
  },
  
  // Question: Interests
  {
    id: '4',
    type: 'question',
    title: 'What interests you most?',
    description: 'Select all that apply',
    icon: '❤️',
    gradient: ['#fa709a', '#fee140'],
    question: {
      id: 'interests',
      type: 'multiple_choice',
      question: 'Choose your interests',
      storageKey: '@user_interests',
      validation: { required: true, minSelections: 1, maxSelections: 3 },
      options: [
        { id: 'freshwater', label: 'Freshwater Fish', icon: '🐟' },
        { id: 'saltwater', label: 'Saltwater Fish', icon: '🐠' },
        { id: 'plants', label: 'Aquatic Plants', icon: '🌿' },
        { id: 'equipment', label: 'Equipment & Tech', icon: '⚙️' },
      ],
    },
  },
  
  // Completion slide
  {
    id: '5',
    type: 'completion',
    title: 'You\'re All Set!',
    description: 'Let\'s start your aquarium journey',
    icon: '🎉',
    gradient: ['#30cfd0', '#330867'],
  },
];

import Slider from '@react-native-community/slider';

<OnboardingScreen
  slides={slides}
  SliderComponent={Slider}
  onComplete={async () => {
    const userData = onboardingStore.getUserData();
    console.log('User answers:', userData.answers);
    // Save to backend, navigate to home, etc.
  }}
/>

📖 API Reference

OnboardingScreen Props

Prop	Type	Default	Description
slides	OnboardingSlide[]	Required	Array of slides to display
onComplete	() => void | Promise<void>	-	Callback when onboarding is completed
onSkip	() => void | Promise<void>	-	Callback when onboarding is skipped
skipButtonText	string	"Skip"	Custom skip button text
nextButtonText	string	"Next"	Custom next button text
getStartedButtonText	string	"Get Started"	Custom get started button text
showSkipButton	boolean	true	Show skip button
showBackButton	boolean	true	Show back button
showProgressBar	boolean	true	Show progress bar
showDots	boolean	true	Show dots indicator
showProgressText	boolean	true	Show progress text (1 of 5)
storageKey	string	-	Custom storage key for completion state
autoComplete	boolean	false	Auto-complete on last slide
SliderComponent	React.ComponentType	-	Required if using slider questions. Import from @react-native-community/slider

OnboardingSlide Interface

interface OnboardingSlide {
  id: string;
  type?: 'info' | 'question' | 'welcome' | 'completion';
  title: string;
  description: string;
  icon: string; // Emoji or Lucide icon name
  gradient: string[]; // [startColor, endColor] or [color1, color2, color3]
  image?: string;
  features?: string[];
  question?: OnboardingQuestion;
  skipIf?: (answers: Record<string, any>) => boolean;
}

Question Types

Single Choice

{
  type: 'single_choice',
  question: 'What is your goal?',
  options: [
    { id: 'weight_loss', label: 'Weight Loss', icon: '🏃' },
    { id: 'muscle_gain', label: 'Muscle Gain', icon: '💪' },
  ],
}

Multiple Choice

{
  type: 'multiple_choice',
  question: 'Select your interests',
  validation: { minSelections: 1, maxSelections: 3 },
  options: [
    { id: 'yoga', label: 'Yoga', icon: '🧘' },
    { id: 'running', label: 'Running', icon: '🏃' },
    { id: 'swimming', label: 'Swimming', icon: '🏊' },
  ],
}

Text Input

{
  type: 'text_input',
  question: 'What is your name?',
  placeholder: 'Enter your name',
  validation: { required: true, minLength: 2, maxLength: 50 },
}

Slider

⚠️ Important: When using slider questions, you must provide the SliderComponent prop to OnboardingScreen:

import Slider from '@react-native-community/slider';

<OnboardingScreen
  slides={slides}
  SliderComponent={Slider}
  onComplete={handleComplete}
/>

{
  type: 'slider',
  question: 'What is your age?',
  validation: { min: 18, max: 100 },
  defaultValue: 25,
}

Note: Make sure @react-native-community/slider is installed and properly linked (run pod install for iOS).

Rating

{
  type: 'rating',
  question: 'Rate your experience',
  validation: { max: 5 },
}

🎨 Customization

Custom Header

<OnboardingScreen
  slides={slides}
  renderHeader={({ isFirstSlide, onBack, onSkip }) => (
    <View>
      {!isFirstSlide && <Button onPress={onBack}>Back</Button>}
      <Button onPress={onSkip}>Skip</Button>
    </View>
  )}
/>

Custom Footer

<OnboardingScreen
  slides={slides}
  renderFooter={({ currentIndex, totalSlides, isLastSlide, onNext }) => (
    <View>
      <Text>{currentIndex + 1} / {totalSlides}</Text>
      <Button onPress={onNext}>
        {isLastSlide ? 'Get Started' : 'Next'}
      </Button>
    </View>
  )}
/>

Conditional Slides

{
  id: '3',
  title: 'Advanced Features',
  description: 'Only for experienced users',
  icon: '⚡',
  gradient: ['#667eea', '#764ba2'],
  skipIf: (answers) => answers.experience_level === 'beginner',
}

💾 Accessing User Data

import { useOnboarding } from '@umituz/react-native-onboarding';

const { userData, getAnswer } = useOnboarding();

// Get specific answer
const experienceLevel = getAnswer('experience_level');

// Get all answers
const allAnswers = userData.answers;

// Check if onboarding was completed
const isComplete = userData.completedAt !== undefined;

// Check if onboarding was skipped
const wasSkipped = userData.skipped === true;

🔄 Resetting Onboarding

import { useOnboarding } from '@umituz/react-native-onboarding';

const { reset } = useOnboarding();

// Reset onboarding (useful for testing or settings)
await reset();

📱 Platform Support

• ✅ iOS
• ✅ Android
• ✅ Web

🏗️ Architecture

Built with Domain-Driven Design (DDD):

• Domain Layer: Entities and interfaces (business logic)
• Infrastructure Layer: Storage and hooks (state management)
• Presentation Layer: Components and screens (UI)

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please open an issue or PR.

📧 Support

For issues and questions, please open an issue on GitHub.