react-native-pager-view: a native swipe pager for React Native, and what it costs you

What react-native-pager-view replaces, and who it is for

A swipeable stack of pages is one of those controls that looks trivial in a mockup and turns ugly in a real app. On Android the platform answer is ViewPager2, on iOS it is UIPageViewController, and both expect you to manage fragments or child view controllers, lifecycle callbacks and gesture arbitration. react-native-pager-view puts a single React component in front of both. The README describes it plainly: "This component allows the user to swipe left and right through pages of data. Under the hood it is using the native Android ViewPager and the iOS UIPageViewController implementations."

The audience is narrow and identifiable. You are building an onboarding flow, a media carousel, a gallery or a wizard where each page fills the screen and the swipe itself matters. You want the platform's own physics, not a JavaScript reimplementation of them. The project was extracted from React Native's lean core effort, which the repository advertises with a Lean Core Extracted badge, so it carries the weight of having once been part of the framework rather than being a weekend wrapper.

If your pages are small, adjacent and always visible, this is not the component you want. A pager assumes one page owns the screen at a time.

How the native pager is wired into your React tree

The mechanism is a host component with native backing on both platforms. You write JSX, the component maps to ViewPager2 on Android and UIPageViewController on iOS, and the props you pass are translated into native configuration. There is no virtual list and no layout engine of its own; the native pager owns the scroll position, the gesture and the page lifecycle.

That design produces a constraint the README states directly: "you can only use `View` components as children of `PagerView`". You do not pass an array of data and a render function. You pass mounted children, each with a key, and the pager treats each child as a page. This is a deliberate difference from list-based APIs, and it means page count is decided at render time by how many children you give it.

Android adds a second trap. The README warns that if a `View` has its own children you should set the `collapsable` prop to false, because otherwise React Native may remove those intermediate views and render the inner children as separate pages. That is not a bug in the pager; it is React Native's view flattening meeting a native container that counts views. The API surface is event-heavy in the same spirit: `onPageScroll` fires while a transition is in progress, whether from animation or from a drag, and `onPageScrollStateChanged` fires when the scrolling state itself changes. Both are described in the prop table as running on both platforms.

Installing react-native-pager-view and rendering a first page

The README gives two package manager options. With Bun the command is `bun add react-native-pager-view`, and with Yarn it is `yarn add react-native-pager-view`. There is no separate native install step for modern React Native, because the README states that on versions 0.60 and above "Autolinking will just do the job." Older projects have to link manually, and the README keeps the CocoaPods and Gradle instructions for them.

bun add react-native-pager-view

After the install, the smallest working pager is a component with a flex style and two View children. The README's own example looks like this, with the `key` prop on each child and `initialPage` selecting the starting index.

import React from 'react';
import { StyleSheet, View, Text } from 'react-native';
import PagerView from 'react-native-pager-view';

const MyPager = () => {
  return (
    <PagerView style={styles.pagerView} initialPage={0}>
      <View key="1">
        <Text>First page</Text>
      </View>
      <View key="2">
        <Text>Second page</Text>
      </View>
    </PagerView>
  );
};

What you should see is a full-height area that swipes horizontally between the two texts. If you nest a wrapper View inside a page and the text starts showing up as its own page, the Android `collapsable` note above is the first thing to check. For anything beyond two pages the README points at the example project rather than expanding the snippet, so `example/src/BasicPagerViewExample.tsx` is the real reference for advanced usage. The repository also ships a Maestro-driven example app; the `package.json` scripts include `example:ios`, `example:android` and `maestro:smoke`, so you can run the project's own smoke test locally instead of guessing at expected behaviour.

New architecture only, and the migration you cannot skip

The most consequential line in the README is a warning: from version 7.x only the new architecture is supported. If your app is still on the old architecture, the current release line is not a drop-in upgrade, and no amount of prop tuning will fix that. The migration guide in MIGRATION.md is the document to read before touching your dependency version.

Version 6.x already removed the `transitionStyle` property, and the README links to MIGRATION.md for the details. So a project that skipped a few major versions has two separate breaks to work through: the architecture requirement and the dropped prop. The package was also renamed at some point from `@react-native-community/viewpager` to `react-native-pager-view`, and the README states that migration information is in the same guide. Three renames and removals across major versions is a normal cost for a native wrapper, but it does mean you should read the changelog rather than trusting a version bump.

The release cadence visible in the repository is tight: v9.0.2 on 2026-08-15, v9.0.3 on 2026-08-31, v9.0.4 on 2026-09-01, with the last push to the default branch on 2026-09-04. That is a project shipping patch releases within days of each other, which is worth knowing when you pin a version. Pin an exact version rather than a caret range if you cannot absorb a patch every fortnight.

Where react-native-pager-view is the wrong choice

There is no web implementation in the repository. The layout is Android, iOS and a visionos folder inside the example app; the package files list covers `src`, `lib`, `android`, `ios` and the podspec. Nothing describes a DOM target. If you need the same pager to run in a browser, this component will not give it to you, and the search interest in a web variant does not change what the repository ships.

The second boundary is behavioural. Because children are mounted views rather than items in a virtualised list, a pager with many heavy pages is a pager with many mounted subtrees. The README does not document a lazy-loading or windowing prop, and it does not document rollback or a fallback path for unsupported architectures either. If your design is a horizontally scrolling feed of dozens of cards, a virtualised list is the better primitive; this component is for a bounded set of full-screen pages.

The third boundary is the tab bar. A pager gives you swipe navigation without a header. If you want labelled tabs that also respond to taps, the pager is only half of that widget, and you would be building the other half yourself.

React-native-tab-view and the difference in approach

The obvious alternative is react-native-tab-view, which appears in the search data around this project. The difference is not cosmetic. react-native-tab-view is the higher-level component: it gives you a tab bar with labels, tap-to-switch behaviour and the swipe gesture together, and it uses a pager underneath to do the swiping. In other words, it is a consumer of this kind of primitive rather than a peer of it.

That reframes the decision. If your screen has a visible tab strip, adopting react-native-pager-view means writing the tab strip, the active-index state and the synchronisation between taps and swipes yourself. If your screen has no tab strip and the swipe is the whole interaction, react-native-tab-view is a layer of abstraction you would be stripping back out. Pick by whether the tabs are part of the UI or not, not by which one has more props.

The second axis is native versus JavaScript. This project deliberately delegates the scroll to the platform pager, which is why the child-component constraint exists and why the new architecture requirement exists. A JavaScript-driven alternative would give you more control over page transitions and a web target, at the cost of matching the platform's gesture feel by hand. Neither is strictly better; they are different bets about what you are willing to maintain.

Licence and the cost of staying current

The repository is MIT licensed, with the LICENSE file at the top level and the badge pointing at the same file. For most applications that is the permissive case: you can use, modify and redistribute the component, and the licence text needs to travel with the source you ship. This is a statement about what the repository declares, not legal advice; if you vendor or fork the native code, have your own counsel read the file.

The upgrade cost is the more practical number. Two things drive it. First, the new architecture requirement from 7.x means the version you can adopt is bounded by where your app already is. Second, patch releases arrive frequently, as the 9.0.2 through 9.0.4 dates show, and each one can touch native code on either platform. A team that pins the version and upgrades deliberately pays a few hours per major version; a team that floats the range pays in intermittent build failures, which is roughly what the search phrase about a failing compileDebugKotlin task suggests people run into. The repository's CI covers lint, iOS build and Android build, so a red build on your machine is more likely to be a local toolchain or architecture mismatch than a broken release.

Editorial conclusion

Adopt react-native-pager-view if you need native swipe paging on Android and iOS and you have already moved to the new architecture, since versions 7.x and later support nothing else. Do not adopt it for a web target, a tab bar, or a project still on the old architecture. Before writing code, confirm your React Native version against the migration guide, then check in the example app whether your page content needs the Android collapsable prop set to false, because that detail decides whether nested views render as separate pages.

Frequently asked questions

Official sources

1. callstack/react-native-pager-view on GitHub
2. Issues
3. License: MIT
4. README
5. Releases