react-native-onboarding-sdk

A visual onboarding SDK for React Native & Expo. Design flows in the Boardy editor, publish them, and render natively in your app — complete with custom Google Fonts, smooth animations, image prefetching, localization, and built-in analytics.

Features

• Visual flow rendering — pixel-perfect screens built from your Boardy editor designs
• CLI setup — npx react-native-onboarding-sdk setup <id> fetches your flow and downloads all required Google Fonts automatically
• Custom fonts — any Google Font used in the editor is downloaded and linked at build time
• Animated transitions — smooth page transitions and loading animations out of the box
• Image prefetching — current, next, and background images are preloaded for instant navigation
• Analytics — step views, button clicks, completion, abandonment, and session tracking with automatic retries
• Localization — automatic country detection via timezone with variant routing per locale
• TypeScript — fully typed API, hooks, and event interfaces

Installation

The fastest way to get started is with the CLI — it installs everything for you:

npx react-native-onboarding-sdk setup <your-onboarding-id>

This single command will:

1. Install react-native-onboarding-sdk into your project if not already installed
2. Install all missing peer dependencies (react-native-reanimated, react-native-safe-area-context, react-native-webview, react-native-responsive-screen, react-native-markdown-display, expo-splash-screen)
3. Detect if expo-font is installed — if not, automatically install it (Expo projects only)
4. Fetch your published onboarding flow from Boardy
5. Download all custom Google Fonts used in your screens to ./assets/fonts/
6. Generate a boardy-fonts.js config that registers fonts at runtime
7. Update app.json — add the expo-font plugin with all downloaded font paths (Expo projects only)

The CLI auto-detects your package manager (npm, yarn, pnpm, or bun) and uses the correct install command.

Manual installation

If you prefer to install manually:

# npm
npm install react-native-onboarding-sdk

# yarn
yarn add react-native-onboarding-sdk

# pnpm
pnpm add react-native-onboarding-sdk

Then install peer dependencies:

npm install react-native-reanimated react-native-safe-area-context react-native-webview react-native-responsive-screen react-native-markdown-display expo-splash-screen expo-font

Quick Start

1. Run the CLI

npx react-native-onboarding-sdk setup <your-onboarding-id>

2. Import the font config

Add this line at the top of your app entry file (e.g. App.tsx or index.js):

require('./assets/fonts/boardy-fonts');

3. Link font assets

Expo (handled automatically by the CLI):

The CLI adds the expo-font plugin to your app.json automatically. If expo-font is not installed, it detects your package manager (npm/yarn/pnpm/bun) and installs it for you. The resulting config looks like:

{
  "expo": {
    "plugins": [
      [
        "expo-font",
        {
          "fonts": [
            "./assets/fonts/Inter-400.ttf",
            "./assets/fonts/Inter-700.ttf"
          ]
        }
      ]
    ]
  }
}

React Native CLI (no Expo):

npx react-native-asset

4. Render the onboarding

import { OnboardingScreens } from 'react-native-onboarding-sdk';

export default function App() {
  return (
    <OnboardingScreens
      onboardingId="YOUR_ONBOARDING_ID"
      onComplete={() => {
        // Navigate to your main app
      }}
      onError={(error) => console.error(error)}
    />
  );
}

API Reference

<OnboardingScreens />

The main component that renders your onboarding flow.

| Prop | Type | Default | Description | |------|------|---------|-------------| | onboardingId | string | — | Required. Your published onboarding ID from Boardy | | apiUrl | string | https://boardy.papyonlab.com | Custom API endpoint | | onComplete | () => void | — | Called when the user finishes the onboarding | | onError | (error: Error) => void | — | Called on fetch or rendering errors | | onLoad | () => void | — | Called when the flow is loaded and ready | | autoHideSplash | boolean | true | Automatically hide the splash screen when loaded | | useLoadingAnimation | boolean | true | Show a loading animation while fetching | | flow | OnboardingFlow | — | Pass a local flow object instead of fetching from API |

useOnboarding hook

For custom UIs — gives you full control over navigation and state.

import { useOnboarding } from 'react-native-onboarding-sdk';

const {
  flow,              // OnboardingFlow | null
  currentStep,       // OnboardingStep | null
  currentStepIndex,  // number
  totalSteps,        // number
  isLoading,         // boolean
  error,             // Error | null
  navigateToStep,    // (index: number) => Promise<void>
  finishOnboarding,  // () => Promise<void>
  trackButtonClick,  // (text: string, action: string) => Promise<void>
} = useOnboarding({
  onboardingId: 'YOUR_ID',
  enableAnalytics: true,  // default: true
  userId: 'optional-user-id',
  onComplete: () => {},
  onError: (err) => {},
});

OnboardingAPI

Direct API client for fetching flows programmatically.

import { OnboardingAPI } from 'react-native-onboarding-sdk';

const api = new OnboardingAPI();

// Basic fetch
const flow = await api.fetchOnboardingFlow('YOUR_ID');

// With automatic localization (recommended)
const localizedFlow = await api.fetchLocalizedOnboardingFlow('YOUR_ID');

OnboardingAnalytics

Standalone analytics tracker.

import { OnboardingAnalytics } from 'react-native-onboarding-sdk';

const deviceInfo = await OnboardingAnalytics.getDeviceInfo();
const analytics = new OnboardingAnalytics(apiUrl, onboardingId, userId, deviceInfo);

await analytics.startSession();
await analytics.trackOnboardingStarted();
await analytics.trackStepViewed(stepId, stepIndex);
await analytics.trackStepCompleted(stepId, stepIndex);
await analytics.trackButtonClicked(stepId, stepIndex, 'Continue', 'navigateTo');
await analytics.trackOnboardingCompleted();

Tracked events:

| Event | When | |-------|------| | onboarding_started | Flow begins loading | | step_viewed | A step becomes visible | | step_completed | User navigates away from a step | | button_clicked | Any button or component tap | | onboarding_completed | User finishes the last step | | onboarding_abandoned | User leaves before completing |

CLI

react-native-onboarding-sdk CLI

Usage:
  npx react-native-onboarding-sdk setup <onboardingId>     Fetch flow & download fonts

Options:
  --output-dir <path>   Font output directory (default: ./assets/fonts)

Example

npx react-native-onboarding-sdk setup OBXIOCFW

  Boardy SDK Setup

  Onboarding ID: OBXIOCFW
  Project root:  /Users/you/myapp
  Font output:   /Users/you/myapp/assets/fonts

  Checking dependencies...

  react-native-onboarding-sdk is not installed. Installing...

    $ yarn add react-native-onboarding-sdk

  Installing 3 missing peer dependencies...

    $ yarn add react-native-reanimated react-native-safe-area-context react-native-webview

  expo-font is not installed. Installing...

    $ yarn add expo-font

  expo-font installed successfully.

  Fetching onboarding flow...
  Found flow: "My App Onboarding" with 5 steps

  Found 3 font(s) to download:

    - Inter (weight: 400)
    - Inter (weight: 700)
    - Playfair Display (weight: 600)

  Downloading Inter 400... done
  Downloading Inter 700... done
  Downloading Playfair Display 600... done

  Generated font config: /Users/you/myapp/assets/fonts/boardy-fonts.js

  Configuring Expo...

  Added expo-font plugin to app.json
  Wrote 3 font path(s) to app.json

  Setup complete! 3/3 font(s) downloaded.

TypeScript

All types are exported for use in your app:

import type {
  OnboardingFlow,
  OnboardingStep,
  OnboardingButton,
  OnboardingScreensProps,
  AnalyticsEvent,
  AnalyticsSession,
} from 'react-native-onboarding-sdk';

How It Works

1. Design your onboarding screens in the Boardy editor
2. Publish your flow — you get an onboarding ID
3. Run npx react-native-onboarding-sdk setup <id> to download fonts used in your design
4. Render with <OnboardingScreens onboardingId="..." /> in your app
5. Track user behavior automatically via built-in analytics

The SDK fetches your flow definition from Firestore at runtime, renders each step natively using React Native components, and reports analytics events back to your Boardy dashboard.

License

MIT