react-native-pager-view

PagerView lets users swipe left and right (or up and down) through pages of content. It is a native component: on Android it renders a Jetpack Compose pager, and on iOS a SwiftUI paged TabView. See it in action!

Installation

npm install react-native-pager-view
# or
yarn add react-native-pager-view
# or
bun add react-native-pager-view

The library is autolinked. On iOS, install the pods afterwards:

cd ios && pod install

Compatibility

We support the three latest React Native versions: 0.85, 0.86 and 0.87. Only the New Architecture is supported.

Usage

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

export function 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>
  );
}

const styles = StyleSheet.create({
  pagerView: {
    flex: 1,
  },
});

Each direct child of PagerView becomes one page and is stretched to fill the pager. Give every child a unique key.

To control the pager from code, keep a ref and call its methods:

const ref = useRef<PagerView>(null);

// ...
<PagerView ref={ref} style={{ flex: 1 }}>
  {pages}
</PagerView>;

// later
ref.current?.setPage(2);

For more examples, see the example app: nested pagers, keyboard handling, tab views, pagination dots, carousels and more.

API

Props

PagerView also accepts all standard View props.

Methods

Types

The package exports these TypeScript types: PagerViewProps, PagerViewOnPageScrollEvent, PagerViewOnPageSelectedEvent, PageScrollStateChangedNativeEvent, and their *EventData payloads.

usePagerView hook

usePagerView bundles the state and handlers you usually wire up yourself: the ref, the active page, the scroll state, the scroll progress, and helpers to add or remove pages and to toggle scrolling, animation and overdrag. It also returns AnimatedPagerView, which is PagerView wrapped with Animated.createAnimatedComponent.

import { View, Text } from 'react-native';
import { usePagerView } from 'react-native-pager-view';

export function PagerHookExample() {
  const { AnimatedPagerView, ref, ...rest } = usePagerView({ pagesAmount: 10 });

  return (
    <AnimatedPagerView
      ref={ref}
      style={{ flex: 1 }}
      initialPage={0}
      scrollEnabled={rest.scrollEnabled}
      overdrag={rest.overdrag}
      onPageScroll={rest.onPageScroll}
      onPageSelected={rest.onPageSelected}
      onPageScrollStateChanged={rest.onPageScrollStateChanged}
    >
      {rest.pages.map((page) => (
        <View key={page}>
          <Text>{`Page ${page}`}</Text>
        </View>
      ))}
    </AnimatedPagerView>
  );
}

The returned object also includes activePage, progress, scrollState, setPage, addPage, removePage, toggleScroll, toggleAnimation and toggleOverdrag. See the full example.

Reanimated onPageScroll handler

To handle onPageScroll on the UI thread with Reanimated, build an event handler with useEvent and pass it to an animated PagerView:

import PagerView from 'react-native-pager-view';
import Animated, { useEvent, useHandler } from 'react-native-reanimated';

const AnimatedPagerView = Animated.createAnimatedComponent(PagerView);

function usePageScrollHandler(handlers, dependencies) {
  const { context, doDependenciesDiffer } = useHandler(handlers, dependencies);

  return useEvent(
    (event) => {
      'worklet';
      const { onPageScroll } = handlers;
      if (onPageScroll && event.eventName.endsWith('onPageScroll')) {
        onPageScroll(event, context);
      }
    },
    ['onPageScroll'],
    doDependenciesDiffer
  );
}

function MyPager() {
  const handler = usePageScrollHandler({
    onPageScroll: (e) => {
      'worklet';
      console.log(e.offset, e.position);
    },
  });

  return <AnimatedPagerView style={{ flex: 1 }} onPageScroll={handler} />;
}

See the full example.

Preview

Android

iOS

Migration

• 8.x → 9.x: the Android implementation moved from ViewPager2 to Jetpack Compose. The JavaScript API did not change.
• 7.x → 8.x: the iOS implementation moved from UIPageViewController to SwiftUI. The JavaScript API did not change.
• 6.x → 7.x: only the New Architecture is supported. Enable it in your app before upgrading.

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT