Pager

Swipe between React Native pages on iOS, Android, and web

One.UI.Pager shows one child view per page and swipes between them. iOS uses a paging UIScrollView, Android uses ViewPager2, and web uses CSS scroll snap.

• Every page stays in the React tree, so state and context survive a swipe.
• onPageScroll reports continuous progress during drags and settles.
• The ref moves pages with or without animation.
• It replaces react-native-pager-view without other changes.

Usage

Give the pager a size and give each page a stable key. Each direct child fills the pager.

import { useRef, useState } from 'react'
import { One, type PagerRef } from 'one'
import { Button, Text, View } from 'react-native'

export function Onboarding() {
  const pager = useRef<PagerRef>(null)
  const [page, setPage] = useState(0)

  return (
    <View style={{ flex: 1 }}>
      <One.UI.Pager
        ref={pager}
        style={{ flex: 1 }}
        onPageSelected={({ nativeEvent }) => setPage(nativeEvent.position)}
      >
        <View key="welcome">
          <Text>Welcome</Text>
        </View>
        <View key="sync">
          <Text>Sync</Text>
        </View>
        <View key="done">
          <Text>Done</Text>
        </View>
      </One.UI.Pager>
      <Button
        title={page === 2 ? 'Start' : 'Next'}
        onPress={() => pager.current?.setPage(Math.min(page + 1, 2))}
      />
    </View>
  )
}

onPageScroll sends position + offset as a continuous value. Use it as the only writer of scroll progress, for example in a Reanimated shared value, and derive indicators from it.

const progress = useSharedValue(0)

<One.UI.Pager
  style={{ height: 360 }}
  onPageScroll={({ nativeEvent }) => {
    progress.set(nativeEvent.position + nativeEvent.offset)
  }}
>
  {pages}
</One.UI.Pager>

API reference

Pager also accepts React Native ViewProps. style sizes the pager itself.

Every event has the shape { nativeEvent }.

Import the type from one and pass a ref to the pager.

An index must be a nonnegative integer; anything else throws. An index past the last page does nothing. A call made before the pager lays out moves it to that page on first layout.

Behavior

• Removing the selected page when it is last selects the new last page.
• A resize keeps the selected page.
• Invalid prop values throw during render on every platform.
• The pager adds no safe area or keyboard insets. Pages own them.
• Nested pagers on Android hand a swipe to the inner pager until it reaches its edge.

For SwiftUI pages with string selection and One.iOS.Page children, use One.iOS.Pager.

Migrating from react-native-pager-view

Replace the default import and JSX with One.UI.Pager, and type the ref as PagerRef from one. The props, events, and ref methods keep their names and payloads.