react-native-onboarding-swiper: A Configurable Welcome Flow for React Native

One Component and Three Worked Examples

react-native-onboarding-swiper is described as delightful onboarding for your React Native app, and the README makes a claim about the React Native ecosystem that is worth repeating: there are many ways to onboard people to a mobile app, but for React Native there is solely one component that is easy to set up and highly customizable.

The component is called Onboarding and it is imported from the package name:

npm i react-native-onboarding-swiper

import Onboarding from 'react-native-onboarding-swiper';

<Onboarding
  pages={[
    {
      backgroundColor: '#fff',
      image: <Image source={require('./images/circle.png')} />,
      title: 'Onboarding',
      subtitle: 'Done with React Native Onboarding Swiper',
    },
    ...
  ]}
/>

The README points to three example files, a simple example at examples/Simple.js, an example with a call-to-action button at examples/WithCTA.js, and an example with custom button components at examples/CustomButtons.js. There is also an Expo snack that runs in the browser and a video tutorial, which is the fastest way to see the whole thing moving before you wire it into an app.

The package itself is small. The main entry is src/index.js with TypeScript declarations in index.d.ts, and the only runtime dependency is tinycolor2, which is there so the component can work out whether text should be dark or light on a given background.

The pages Array and Its Required Shape

Everything the component shows comes from the pages prop, which is required and is an array of page objects. Each page has a fixed shape.

The image is required, and it is a component such as an Image to display at the top of the page. The title is required, and it is a string or a React Native component, so you can render a formatted heading rather than a plain string. The subtitle is required, with the same string or component choice.

The background is optional, and the choice is either backgroundColor, a background colour, or background, a React element rendered behind the page content, for example a LinearGradient. The README makes a specific recommendation about combining them, and it is a good one: use background for the visual, since that is what keeps the library from depending on any gradient package, and use backgroundColor as well, because the solid colour provides the smooth animated transitions between pages while the background element handles the visuals.

So the color and the decoration are separated on purpose. The colour drives the animation and the contrast calculation, and the element is the artwork.

Then there are the style overrides that apply to the pages in the array rather than to one page: containerStyles for the default container styles, imageContainerStyles for the image container, for example the paddingBottom of 60, titleStyles and subTitleStyles. Those override the styles the component sets, rather than working alongside them.

Automatic Contrast and the isLight Override

The component works out the text and dot colours from the page background, and the README describes the behaviour in one line: the colour of the font and dots adapts to the background colour. That is where tinycolor2 comes in, since deciding whether white or black text is readable on an arbitrary background needs a colour analysis rather than a comparison.

The override is isLight, a boolean. When it is true, text and dots use dark colours, and when it is false they use light colours. The documented use case is a background element, because the library cannot automatically detect brightness from a gradient.

The default is stated precisely: it is false when neither backgroundColor nor isLight is provided. So a page with only a background element and no explicit choice gets light text, which is a reasonable default for a dark gradient and the wrong one for a pale one, and isLight is how you say so.

Two other props in the same family are worth knowing. controlStatusBar, a boolean defaulting to true, controls whether the status bar changes with the background colour, and allowFontScalingText and allowFontScalingButtons, both defaulting to true, exist because font scaling can cause trouble on high resolution screens and you may want to disable it.

Buttons: Labels, Visibility, Callbacks and skipToPage

The bottom bar carries the navigation, and every part of it is configurable.

The Next button has nextLabel, a string or a React Native component, defaulting to Next, and showNext, a boolean defaulting to true. The Skip button has skipLabel, defaulting to Skip, and showSkip, also defaulting to true. The Done checkmark has showDone, defaulting to true.

The callbacks are onSkip, fired if the onboarding is skipped, onNext, fired when the Next button is pressed, and onDone, fired after the onboarding is completed.

skipToPage is the one with a real interaction between props. When pressing skip, it goes to that page, for example skipToPage={2}, and the README notes that if this prop is provided it ignores onSkip. So the two ways of handling a skip are mutually exclusive, and which one wins is determined by whether skipToPage is set.

The bar itself has bottomBarHeight, a number defaulting to 60, bottomBarColor, defaulting to transparent, and bottomBarHighlight, a boolean defaulting to true for whether the bottom bar should be highlighted.

The README also documents that each page can override the global button labels, which is how a flow with a different call to action on the last page is built without a second component.

Gating the Flow With canSwipeForward

The most useful feature for a real onboarding flow is the per-page navigation conditions, and they exist to require an action before the user proceeds.

For each page you can set canSwipeForward and canSwipeBackward, both booleans defaulting to true. When canSwipeForward is false, forward swiping is blocked and the Next, Done and Skip buttons are disabled. When canSwipeBackward is false, backward swiping is blocked.

The README gives the case it is built for, requiring the user to complete an action such as filling a form or accepting terms before proceeding, and shows how it is driven by state:

<Onboarding
  pages={[
    {
      backgroundColor: '#fff',
      image: <Image source={require('./images/form.png')} />,
      title: 'Fill the form',
      subtitle: 'Complete all fields to continue',
      canSwipeForward: formIsValid,
    },
    ...
  ]}
/>

The mechanism is to update the pages array with new state, so the gate opens and closes as the underlying state changes.

There is one important caveat, and it is stated in the README as a note. The imperative goToPage() method is not affected by these conditions and can always navigate to any page. So the gate stops the user, but not your own code, which is the right behaviour for a controlled flow, and also a trap if you assume the gate is a security boundary. It is a user interface constraint, not a validation one.

Controlled and Uncontrolled Modes, and the FlatList Underneath

The component supports both ways of driving the current page, and the props are named the way you would expect.

currentPage is a number that controls the currently visible page from the parent. When this prop changes, the component scrolls to the given page, and the README recommends it for resetting to the first page when the user navigates back to the screen. Its default is null, which is the uncontrolled mode.

pageIndexCallback is a function that receives the page index as a parameter on page change, which is how you keep your own state in step with the swiper.

Underneath, the pages are held in a FlatList, and flatlistProps lets you pass additional props to it. That is the escape hatch for the list itself, things like initialNumToRender, windowSize or a keyExtractor, and it is worth knowing it exists because it is the only way to tune the list behaviour without forking.

The animation is also configurable, with transitionAnimationDuration setting the duration in milliseconds for the animation of the background colour for the page transition, defaulting to 500. And showPagination, defaulting to true, controls whether the bottom pagination bar is shown, which is the row of dots indicating where you are.

The Package Shape and the Maintenance Picture

The repository is a small React Native component library. There is src/ with the implementation, examples/ with the three worked examples, an expo-example/ directory, a demo/ folder with the screenshots and the demo gif used in the README, an index.d.ts for TypeScript users, a babel.config.js for the build, and jest.config.js with jest.setup.js for the tests. The test suite runs on Jest with @testing-library/react-native as the testing library, and the scripts are the standard test, test:watch and test:coverage trio.

The dependency policy is unusually light. There is exactly one runtime dependency, tinycolor2, and the peer dependencies are prop-types, react and react-native, all at the wildcard version, meaning the component does not constrain what React Native version you are on. The dev dependencies pin React 19 and React Native 0.78 for development, and the linting stack is the Airbnb configuration with the React, React Native, import, JSX accessibility and Prettier plugins.

The version and the maintenance picture are the two things to check. The package version is 1.4.0, the repository publishes no GitHub releases, and the last push was on 2026-06-10, with a CHANGELOG.md at the root recording the changes. So the npm version is the reference point, and a project that pins its dependencies should pin 1.4.0 rather than tracking a branch.

Editorial conclusion

react-native-onboarding-swiper fits a React Native app that needs a first-run walkthrough in a day, since the whole surface is one component with a pages array and a set of labelled props, and it does not fit a product that needs per-page analytics, per-page persistence or a fully bespoke bottom bar, because the component owns the chrome. Before adopting it, check the peer dependency range, which is wide open at prop-types, react and react-native with any version, and read the note that the imperative goToPage() method ignores the per-page swipe conditions, since that is the way to accidentally let a user past a gate. The package is MIT licensed at version 1.4.0, the last push was on 2026-06-10, and it publishes no GitHub releases, so the npm version is the one to track.

Frequently asked questions

Official sources

1. Issues
2. jfilter/react-native-onboarding-swiper on GitHub
3. Project website
4. README