PagerView

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.

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

PagerView

Type: React.Element<PagerViewProps>

A drop-in replacement for react-native-pager-view. Renders a horizontally paged view backed by Jetpack Compose's HorizontalPager on Android and SwiftUI on iOS. Each child is treated as a separate page.

Props for the PagerView component. Compatible with react-native-pager-view.

PagerViewProps

children

Optional • Type: ReactNode

Pages of the pager. Each child is treated as a separate page and stretched to fill the pager. Each child should have a stable key.

initialPage

Optional • Type: number • Default: 0

Index of the page that is initially selected. Read once on mount; later changes are ignored. To navigate after mount, call ref.setPage() or ref.setPageWithoutAnimation().

onPageScroll

Optional • Type: (event: PagerViewOnPageScrollEvent) => void

Fires continuously while a swipe is in progress. The event's position is the index of the leading visible page; offset is the fractional progress toward the next page in the [0, 1) range.

Mark this handler with 'worklet' (requires react-native-worklets) to run it synchronously on the UI thread every frame.

onPageScrollStateChanged

Optional • Type: (event: PageScrollStateChangedEvent) => void

Fires when the scroll state changes between idle, dragging, and settling.

onPageSelected

Optional • Type: (event: PagerViewOnPageSelectedEvent) => void

Fires when a page is fully selected. The event's position is the index of the new page.

ref

Optional • Type: Ref<PagerViewRef>

Ref handle exposing imperative setPage, setPageWithoutAnimation, and setScrollEnabled methods.

scrollEnabled

Optional • Type: boolean • Default: true

Whether the user can swipe between pages.

Inherited props

• ViewProps

Types

PagerViewOnPageScrollEvent

Type: NativeSyntheticEvent<PagerViewOnPageScrollEventData>

PagerViewOnPageScrollEventData

Type: Readonly<{ offset: number, position: number }>

PagerViewOnPageSelectedEvent

Type: NativeSyntheticEvent<PagerViewOnPageSelectedEventData>

PagerViewOnPageSelectedEventData

Type: Readonly<{ position: number }>

PagerViewRef

Ref handle for the PagerView component.

PageScrollStateChangedEvent

Type: NativeSyntheticEvent<PageScrollStateChangedEventData>

PageScrollStateChangedEventData

Type: Readonly<{ pageScrollState: 'idle' | 'dragging' | 'settling' }>