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.86, 0.87 and 0.88. 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

| Prop | Description | Platform | | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | :------: | | initialPage: number | Index of the page that is selected on mount. | both | | scrollEnabled: boolean | Whether the user can swipe between pages. Defaults to true. | both | | orientation: 'horizontal' \| 'vertical' | Scroll direction. Defaults to horizontal. Changing it after mount is not supported. | both | | layoutDirection: 'ltr' \| 'rtl' \| 'locale' | Layout direction. Use ltr or rtl to set it explicitly, or locale to follow I18nManager.isRTL. Defaults to locale. | both | | pageMargin: number | Blank space between pages. | both | | keyboardDismissMode: 'none' \| 'on-drag' | Whether the keyboard is dismissed when the user drags the pager. Defaults to none. | both | | onPageScroll: (e: PagerViewOnPageScrollEvent) => void | Called while moving between pages, either from a swipe or from an animated setPage. e.nativeEvent contains position and offset. | both | | onPageSelected: (e: PagerViewOnPageSelectedEvent) => void | Called once the pager settles on a page, and once on mount for initialPage. e.nativeEvent.position is the selected index. | both | | onPageScrollStateChanged: (e: PageScrollStateChangedNativeEvent) => void | Called when the scroll state changes. e.nativeEvent.pageScrollState is idle, dragging or settling. | both | | overdrag: boolean | Allows bouncing past the first and last page. Defaults to false. | iOS | | offscreenPageLimit: number | Number of pages kept composed on each side of the visible page. When unset, the Compose pager default is used. | Android | | overScrollMode: 'auto' \| 'always' \| 'never' | Overscroll effect at the edges. never disables the effect. Defaults to auto. | Android |

PagerView also accepts all standard View props.

Methods

| Method | Description | Platform | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | | setPage(index: number) | Scrolls to the given page with an animation. An invalid index is ignored. | both | | setPageWithoutAnimation(index: number) | Jumps to the given page without an animation. An invalid index is ignored. | both | | setScrollEnabled(scrollEnabled: boolean) | Enables or disables swiping imperatively. Prefer the scrollEnabled prop; use this when a re-render would get in the way, for example during an animation. | both |

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

| horizontal | vertical | | :---------------------------------------------------------------: | :------------------------------------------------------------------------: | | | |

iOS

| horizontal | vertical | | :------------------------------------------------------------------: | :--------------------------------------------------------------------: | | | |

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