This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

A PagerView component with an API compatible with react-native-pager-view. It wraps the platform-specific @expo/ui primitives: Jetpack Compose HorizontalPager on Android and a paged SwiftUI ScrollView on iOS. Each child becomes a separate page and stretches to fill the pager.

If you need lower-level control over platform-specific paging behavior or modifiers, use the native primitives directly. On iOS, TabView with the page style also renders a horizontal pager and may fit better when you want SwiftUI's built-in page indicators.

Installation

If you are installing this in an existing React Native app, make sure to install expo in your project.

Optionally, install react-native-worklets if you need either of the following:

• Animated setPage on iOS. Without worklets, iOS setPage falls back to a non-animated jump. Android animates regardless.
• Per-frame onPageScroll callbacks that stay on the UI thread. When your onPageScroll handler is itself a worklet, it runs synchronously on the UI thread every frame instead of hopping to JS. Without worklets the callback still fires — it just runs on the JS thread.

Migrating from react-native-pager-view

Update the import statement by importing PagerView from @expo/ui/community/pager-view:

import PagerView from 'react-native-pager-view';
// becomes:
import PagerView from '@expo/ui/community/pager-view';

Before you swap, you should know what changes:

• orientation="vertical", keyboardDismissMode, overdrag, and overScrollMode are not supported.
• The usePagerView hook is not provided — use a ref instead.
• On iOS, onPageScroll and onPageScrollStateChanged only fire on iOS 18+.

See Platform behavior for the full list.

Basic usage

import { useRef } from 'react';
import { Button, StyleSheet, Text, View } from 'react-native';
import PagerView, { type PagerViewRef } from '@expo/ui/community/pager-view';

export default function PagerViewExample() {
  const pagerRef = useRef<PagerViewRef>(null);

  return (
    <View style={{ flex: 1 }}>
      <PagerView
        ref={pagerRef}
        style={{ flex: 1 }}
        initialPage={0}
        onPageSelected={event => {
          console.log('selected page', event.nativeEvent.position);
        }}>
        <View key="one" style={[styles.page, { backgroundColor: '#fde68a' }]}>
          <Text>Page one</Text>
        </View>
        <View key="two" style={[styles.page, { backgroundColor: '#bfdbfe' }]}>
          <Text>Page two</Text>
        </View>
        <View key="three" style={[styles.page, { backgroundColor: '#bbf7d0' }]}>
          <Text>Page three</Text>
        </View>
      </PagerView>

      <Button title="Go to page 2" onPress={() => pagerRef.current?.setPage(1)} />
    </View>
  );
}

const styles = StyleSheet.create({
  page: { flex: 1, alignItems: 'center', justifyContent: 'center' },
});

Platform behavior

Web is not supported and rendering PagerView on web throws at runtime.

Additional differences from upstream react-native-pager-view:

• orientation="vertical", keyboardDismissMode, overdrag, and overScrollMode are not supported. Only horizontal paging is available, and the others fall back to the platform pager's defaults.
• The usePagerView hook is not provided. Use a ref to PagerView to access setPage, setPageWithoutAnimation, and setScrollEnabled.
• setScrollEnabled triggers a re-render so the new value flows through to the native view as a prop. It is still useful for toggling from non-React contexts such as a ref-based gesture handler.
• The borderRadius style applies on both platforms. On Android, only numeric values clip the pager. The underlying Compose host silently drops string values such as '50%'.

API

import PagerView from '@expo/ui/community/pager-view';

Component

Types