@ahmat-2000/react-native-onboarding

A lightweight and flexible onboarding flow for React Native powered by Reanimated.

Built around a headless core:

• horizontal paging
• animated background interpolation
• onboarding state & hooks
• safe area support
• fully custom UI support

Optional helper components are included for rapid setup.

Features

• Horizontal onboarding pager
• Reanimated-powered scroll tracking
• Background color interpolation between slides
• Headless architecture
• Compound API
• Safe area support
• Shared onboarding context
• Per-slide progress hooks
• Optional helper UI components
• TypeScript support
• Expo compatible
• React Native New Architecture compatible

Installation

npm install @ahmat-2000/react-native-onboarding

Install peer dependencies:

npm install react-native-reanimated react-native-safe-area-context react-native-worklets

Peer dependencies

| Package | Version | | ------------------------------ | ------- | | react | >= 19 | | react-native | >= 0.83 | | react-native-reanimated | >= 4 | | react-native-safe-area-context | >= 5 | | react-native-worklets | >= 0.7 |

Reanimated setup

Add the Reanimated plugin inside your Babel config.

module.exports = {
  presets: ["babel-preset-expo"],
  plugins: ["react-native-reanimated/plugin"],
};

Wrap your app with:

import { SafeAreaProvider } from "react-native-safe-area-context";

export default function App() {
  return (
    <SafeAreaProvider>
      <Root />
    </SafeAreaProvider>
  );
}

Quick Start

import { Text, View } from "react-native";
import { Onboarding } from "@ahmat-2000/react-native-onboarding";

export default function App() {
  return (
    <Onboarding onDone={() => console.log("done")}>
      <Onboarding.Slide backgroundColor="#dbeafe">
        <View style={{ flex: 1, justifyContent: "center" }}>
          <Text>Welcome</Text>
        </View>
      </Onboarding.Slide>

      <Onboarding.Slide backgroundColor="#fce7f3">
        <View style={{ flex: 1, justifyContent: "center" }}>
          <Text>Features</Text>
        </View>
      </Onboarding.Slide>

      <Onboarding.Bottom>
        <Onboarding.SkipButton />
        <Onboarding.Dots />
        <Onboarding.NextButton />
      </Onboarding.Bottom>
    </Onboarding>
  );
}

Philosophy

This library separates:

• onboarding behavior
• onboarding UI

The core handles:

• paging
• navigation
• scroll state
• progress interpolation
• slide state

Helpers are optional.

You can build a completely custom onboarding experience using hooks and React Native primitives.

Core Architecture

core/
├── OnboardingRoot.tsx
├── Slide.tsx
├── context.ts
├── hooks.ts
└── types.ts

Core responsibilities

OnboardingRoot

• horizontal pager
• onboarding state
• animated scroll handling
• context provider
• background interpolation
• navigation methods

Slide

• slide container
• per-slide context
• slide progress integration

Hooks

• useOnboarding()
• useSlide()
• useSlideProgress()

Helpers

helper/
├── Bottom.tsx
├── Dots.tsx
├── NextButton.tsx
└── SkipButton.tsx

Helpers are intentionally lightweight and replaceable.

They exist for convenience, not to impose a design system.

Compound API

<Onboarding>
  <Onboarding.Slide />

  <Onboarding.Bottom>
    <Onboarding.SkipButton />
    <Onboarding.Dots />
    <Onboarding.NextButton />
  </Onboarding.Bottom>
</Onboarding>

Fully Custom UI

You are not required to use helpers.

import {
  OnboardingRoot,
  Slide,
  useOnboarding,
} from "@ahmat-2000/react-native-onboarding";

function Footer() {
  const { index, count, goNext, isLast, onDone } =
    useOnboarding();

  return (
    <View>
      <Text>
        {index + 1} / {count}
      </Text>

      <Button
        title={isLast ? "Done" : "Next"}
        onPress={() => {
          if (isLast) {
            onDone();
          } else {
            goNext();
          }
        }}
      />
    </View>
  );
}

export default function App() {
  return (
    <OnboardingRoot onDone={() => {}}>
      <Slide backgroundColor="#dbeafe">
        <View />
      </Slide>

      <Slide backgroundColor="#fce7f3">
        <View />
      </Slide>

      <Footer />
    </OnboardingRoot>
  );
}

Hooks

useOnboarding()

Access onboarding state and navigation.

const {
  index,
  count,
  isFirst,
  isLast,
  goNext,
  goPrev,
  goTo,
} = useOnboarding();

useSlide()

Access current slide metadata.

const { index } = useSlide();

useSlideProgress()

Returns a Reanimated derived value normalized between:

-1 → previous
 0 → centered
+1 → next

Perfect for:

• parallax
• opacity
• scale
• translate animations

API

Onboarding / OnboardingRoot

| Prop | Type | Description | | --------------------- | --------------- | -------------------------------- | | onDone | () => void | Called when onboarding completes | | onSkip | () => void | Optional skip callback | | style | ViewStyle | Root style | | contentContainerStyle | ViewStyle | Root container style | | scrollViewProps | ScrollViewProps | Additional scroll props | | testID | string | Test identifier |

Slide

| Prop | Type | | --------------- | --------- | | backgroundColor | string | | animated | boolean | | style | ViewStyle |

TypeScript

TypeScript definitions are bundled with the package.

No additional typings required.

Expo compatibility

Compatible with:

• Expo
• Expo Router
• Expo Dev Client
• React Native CLI

Design goals

• Headless first
• UI optional
• Minimal API surface
• Strong TypeScript support
• Predictable behavior
• Easy customization
• Production-ready defaults

Contributing

Issues and PRs are welcome.

GitHub:

• https://github.com/ahmat-2000/react-native-onboarding

License

MIT © Ahmat Mahamat