For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt, and this page is available as Markdown at /next/ui/components/view-pager.md.
lynx-ui logo
lynx-ui
  • English
  • ViewPager

    A page-snapped horizontal content navigator for ReactLynx with optional off-screen lazy rendering.
    Info

    You can check the source code to understand how it works, and you're welcome to submit PRs to enhance its capabilities.

    Basic Usage

    Render data-driven pages and track the current page through change events.

    Examples

    Auto Height

    Let page content determine the pager's natural height without setting one explicitly.

    Dynamic Height

    Interpolate the pager height on the main thread as differently sized pages move.

    Lazy Rendering

    Lazy-render pages and navigate them through imperative controls.

    Nested List

    Combine horizontal paging with independently scrollable vertical lists.

    Structure

    <ViewPager data={pages}>
      {(page, index) => <Page />}
    </ViewPager>

    Component API

    ViewPager

    bouncesiOSAndroid
    Typeboolean·Defaulttrue
    Enable the native spring effect where supported.
    childreniOSAndroid
    Type(item: T, index: number) => ReactNode
    Render page content. Selection state is intentionally not passed, so a native swipe does not require React to rerender page content.
    classNameiOSAndroidHarmony
    Typestring
    className
    dataiOSAndroid
    Typereadonly T[]
    Data rendered as pages. ViewPager creates one direct native viewpager-item child for every entry.
    enableScrolliOSAndroid
    Typeboolean·Defaulttrue
    Enable horizontal swipe gestures.
    getItemKeyiOSAndroid
    Type(item: T, index: number) => string | number
    Return a stable, unique key for an entry. When omitted, the item index is used. Provide this function when items can be inserted, removed, or reordered.
    getItemPropsiOSAndroid
    Type(item: T, index: number) => ViewPagerItemProps
    Native props for an individual generated item. Its class name is added to itemClassName; its style overrides matching itemStyle properties. The item's key, ref, and children are managed by ViewPager.
    idiOSAndroid
    Typestring
    Identifier applied to the native ViewPager root.
    initialSelectIndexiOSAndroid
    Typenumber·Default0
    Initial page index. Later changes are ignored; use ref.scrollToPage to navigate.
    itemClassNameiOSAndroid
    Typestring
    Class name applied to every generated viewpager-item.
    itemStyleiOSAndroid
    TypeCSSProperties
    Style applied to every generated viewpager-item.
    lazyOptionsiOSAndroid
    TypeViewPagerLazyOptions
    Exposure-driven lazy rendering. The initial page renders immediately; other pages render when their placeholders enter the configured exposure area. Rendered pages stay mounted. Omit this prop to render every page.
    main-thread:onOffsetChangeiOSAndroid
    Type(event: ViewPagerOffsetChangeEvent) => void
    Main-thread scroll progress handler. Use a main thread function.
    main-thread:onPageChangeiOSAndroid
    Type(event: ViewPagerChangeEvent) => void
    Main-thread page completion handler. Use a main thread function.
    main-thread:onPageWillChangeiOSAndroid
    Type(event: ViewPagerWillChangeEvent) => void
    Main-thread page transition handler. Use a main thread function.
    onOffsetChangeiOSAndroid
    Type(event: ViewPagerOffsetChangeEvent) => void
    Native scroll progress event. Read its data from event.detail.
    onPageChangeiOSAndroid
    Type(event: ViewPagerChangeEvent) => void
    Native page completion event. Read the selected index from event.detail.index.
    onPageWillChangeiOSAndroid
    Type(event: ViewPagerWillChangeEvent) => void
    Native event before a page transition completes. Read its data from event.detail.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    viewpagerPropsiOSAndroid
    TypeOmit<ViewPagerProps, style | ref | children | id | className | initial-select-index | align-width | enable-scroll | allow-horizontal-gesture | bounces | keep-item-view | bindchange | bindwillchange | bindoffsetchange | main-thread:bindchange | main-thread:bindwillchange | main-thread:bindoffsetchange>
    Native pager attributes not managed by the component.

    ViewPagerRef

    scrollToPageiOSAndroid
    Type(index: number, smooth?: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void
    Slide to a page through the native node ref. Animation defaults to true. Indexes are clamped to available pages. Empty pagers ignore requests. Completion is reported through onPageChange; success confirms invocation.

    Supporting Types

    ViewPagerItemProps

    ViewPagerItemProps
    TypeOmit<NativeViewPagerItemProps, key | ref | children | style> & {style?: unknown}

    ViewPagerExposureMargin

    ViewPagerExposureMargin
    Typepx | rpx

    ViewPagerLazyOptions

    ViewPagerLazyOptions
    Type{enableLazy: false} | {enableLazy: true, exposureLeft?: ViewPagerExposureMargin, exposureRight?: ViewPagerExposureMargin, scene: string}
    Disable lazy rendering.

    ViewPagerChangeEvent

    ViewPagerChangeEvent
    TypeBaseEvent<"bindchange", ViewPagerChange>

    ViewPagerWillChangeEvent

    ViewPagerWillChangeEvent
    TypeBaseEvent<"bindwillchange", ViewPagerChange>

    ViewPagerOffsetChangeEvent

    ViewPagerOffsetChangeEvent
    TypeBaseEvent<"bindchange", ViewPagerOffsetChange>
    Except as otherwise noted, this work is licensed under a Creative Commons Attribution 4.0 International License, and code samples are licensed under the Apache License 2.0.