Skip to main content

Page Types

The SDK includes pre-built renderers for common onboarding patterns.

Overview​

Each page type is designed for a specific onboarding use case. All types share common properties and are customizable through theming, custom components, or custom renderers.

Available Page Types​

Question​

Interactive questions with single or multiple choice answers.

Use cases:

  • User preferences
  • Quiz-style onboarding
  • Survey questions
  • Profile building

Key features:

  • Single or multiple selection
  • Customizable answer buttons
  • Theme-aware styling
  • Support for custom components

Payload:

{
  title: string;
  subtitle?: string;
  answers: Array<{
    label: string;
    value: string;
  }>;
  multipleAnswer: boolean;
}

Example:

{
  id: "preferences",
  type: "Question",
  payload: {
    title: "What are your goals?",
    subtitle: "Select all that apply",
    answers: [
      { label: "Build muscle", value: "muscle" },
      { label: "Lose weight", value: "weight" },
      { label: "Improve flexibility", value: "flexibility" },
    ],
    multipleAnswer: true
  }
}

Dependencies: None

MediaContent​

Display images or videos with title and description.

Use cases:

  • Welcome screens
  • Feature explanations
  • Visual onboarding
  • Tutorial steps

Key features:

  • Image, Lottie, or Rive support
  • Optional title and description
  • Centered media display
  • Responsive sizing

Payload:

{
  title?: string;
  description?: string;
  media: {
    type: "image" | "lottie" | "rive";
    url?: string;
    localPathId?: string;
  };
}

Example:

{
  id: "welcome",
  type: "MediaContent",
  payload: {
    title: "Welcome to FitApp",
    description: "Your personal fitness companion",
    media: {
      type: "image",
      url: "https://example.com/welcome.png"
    }
  }
}

Dependencies: None

Multi-slide horizontal pagination with page indicators.

Use cases:

  • Feature tours
  • Multi-step tutorials
  • Swipeable content
  • Progressive disclosure

Key features:

  • Horizontal scrolling
  • Page indicators (dots)
  • Per-slide media and text
  • Automatic "Next" / "Continue" button labels

Payload:

{
  screens: Array<{
    title?: string;
    description?: string;
    media?: MediaSource;
  }>;
}

Example:

{
  id: "tour",
  type: "Carousel",
  payload: {
    screens: [
      {
        title: "Track Your Progress",
        description: "Monitor your fitness journey",
        media: { type: "image", url: "https://..." }
      },
      {
        title: "Set Goals",
        description: "Define and achieve your targets",
        media: { type: "image", url: "https://..." }
      }
    ]
  }
}

Dependencies: None

Picker​

Type-specific input pickers for structured data.

Use cases:

  • Collect specific user data
  • Profile information
  • Preferences with constrained options

Key features:

  • Native picker UI
  • Type-specific implementations
  • Unit conversions (weight, height)
  • Range validation

Supported types:

  • weight - Weight with kg/lb units
  • height - Height with cm/ft+in units
  • age - Age picker
  • gender - Gender selection
  • name - Name input
  • date - Date picker

Payload:

{
  title: string;
  subtitle?: string;
  pickerType: "weight" | "height" | "age" | "gender" | "name" | "date";
  defaultValue?: string;
}

Example:

{
  id: "user-weight",
  type: "Picker",
  payload: {
    title: "What's your weight?",
    pickerType: "weight",
    defaultValue: "70-kg"
  }
}

Dependencies: @react-native-picker/picker

npx expo install @react-native-picker/picker

Loader​

Sequential progress animation with optional carousel.

Use cases:

  • Loading states
  • Processing animations
  • Wait screens with progress
  • Educational "Did you know?" moments

Key features:

  • Sequential step animations
  • Progress bars (0% → 100%)
  • Checkmarks on completion
  • Optional carousel with images
  • Configurable duration

Payload:

{
  title: string;
  steps: Array<{
    label: string;      // Text while loading
    completed: string;  // Text when done
  }>;
  didYouKnowImages?: Array<MediaSource>;
  duration?: number;    // Milliseconds per step (default: 2000)
}

Example:

{
  id: "analyzing",
  type: "Loader",
  payload: {
    title: "Analyzing your profile",
    steps: [
      {
        label: "Processing data",
        completed: "Data processed"
      },
      {
        label: "Building recommendations",
        completed: "Recommendations ready"
      }
    ],
    duration: 2000
  }
}

Dependencies: None

Ratings​

App store rating prompts with social proof.

Use cases:

  • Request app reviews
  • Show user testimonials
  • Build trust with social proof
  • Increase app ratings

Key features:

  • Star rating UI
  • Opens native App Store review
  • Social proof cards (optional)
  • Customizable testimonials

Payload:

{
  title: string;
  subtitle?: string;
  socialProofs?: Array<{
    name: string;
    rating: number;
    comment: string;
    avatar?: string;
  }>;
}

Example:

{
  id: "rate-us",
  type: "Ratings",
  payload: {
    title: "Enjoying FitApp?",
    subtitle: "Your feedback helps us improve!",
    socialProofs: [
      {
        name: "Sarah M.",
        rating: 5,
        comment: "This app changed my life!",
      }
    ]
  }
}

Dependencies: expo-store-review

npx expo install expo-store-review

Commitment​

User commitment and agreement screens.

Use cases:

  • Terms acceptance
  • Commitment statements
  • Agreements
  • Signature collection

Key features:

  • Checkbox for agreement
  • Optional signature (requires Skia)
  • Info boxes for important notes
  • Required acknowledgment before continuing

Payload:

{
  title: string;
  subtitle?: string;
  commitmentText: string;
  requireSignature?: boolean;
  infoBoxes?: Array<{
    title: string;
    description: string;
    icon?: string;
  }>;
}

Example:

{
  id: "terms",
  type: "Commitment",
  payload: {
    title: "Terms of Service",
    commitmentText: "I agree to the Terms of Service and Privacy Policy",
    requireSignature: false,
    infoBoxes: [
      {
        title: "Privacy First",
        description: "We never share your data without permission"
      }
    ]
  }
}

Dependencies (signature only): @shopify/react-native-skia

npx expo install @shopify/react-native-skia

Common Properties​

All page types share these properties:

{
  id: string;                    // Unique identifier
  type: string;                  // Discriminated union field
  name: string;                  // Display name (for debugging)
  displayProgressHeader: boolean; // Show/hide progress bar
  payload: object;               // Type-specific data
  customPayload: object | null;  // Your custom fields
  continueButtonLabel?: string;  // Optional CTA text
  figmaUrl?: string | null;      // Design reference
}

Customization Levels​

Each page type supports three levels of customization:

Level 1: Theming​

Apply theme tokens to all screens:

<OnboardingProvider
  theme={{
    colors: { primary: "#FF5733" },
    typography: { fontFamily: { title: "CustomFont" } }
  }}
/>

Learn more about theming →

Level 2: Custom Components​

Replace specific UI components (currently available for Question type):

<OnboardingProvider
  customComponents={{
    QuestionAnswerButton: MyCustomButton
  }}
/>

Learn more about custom components →

Level 3: Custom Renderers​

Complete control over specific screens:

// In your routing file
if (step.id === "custom-screen") {
  return <MyCustomRenderer step={step} onContinue={onContinue} />;
}

Learn more about custom renderers →

Media Support​

Several page types support media with the MediaSourceSchema:

{
  type: "image" | "lottie" | "rive";
  url?: string;          // Remote URL
  localPathId?: string;  // Local asset path
}

Supported media types:

  • image: PNG, JPG, WebP via React Native Image
  • lottie: Lottie animations (implementation pending)
  • rive: Rive animations (implementation pending)

Using Individual Renderers​

You can use renderers directly without OnboardingPage:

import { MediaContentRenderer, MediaContentStepType } from "@rocapine/react-native-onboarding";

const step: MediaContentStepType = {
  id: "welcome",
  type: "MediaContent",
  name: "Welcome",
  displayProgressHeader: true,
  payload: {
    title: "Welcome!",
    description: "Let's get started",
    media: { type: "image", url: "https://..." },
  },
  customPayload: null,
  continueButtonLabel: "Get Started",
  figmaUrl: null,
};

<MediaContentRenderer step={step} onContinue={handleContinue} />

Next Steps​