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/scroll-view.md.
lynx-ui logo
lynx-ui
  • English
  • ScrollView

    A ScrollView component for ReactLynx. It provides scrolling primitives and bounce handling.
    • Lazy-loading optimized container powered by LazyComponent, designed to reduce first-screen rendering time

    • Native bounces across Android, iOS, and Harmony with the new scroll-view architecture

    Info

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

    Basic Usage
    Under the `bounceableOptions`

    Basic Usage

    Use <ScrollView> to enable scrollable content.

    Structure

    <ScrollView>
      {/* Your content */}
    </ScrollView>

    Component API

    ScrollView

    Properties
    androidTouchSlopAndroid
    Typedefault | paging
    Android touch recognition mode. When inside a component that supports 'paging' mode, 'paging' must be enabled.
    bounceableiOSAndroid
    Typeboolean
    Enable bouncing effect
    bounceableOptionsiOSAndroid
    Typeboolean | BounceableBasicProps·Default{ enableBounces: true, singleSidedBounce: "iOSBounces" },
    Props for bouncing effect
    childreniOSAndroid
    TypeReactNode
    Children in scroll-view.
    classNameiOSAndroidHarmony
    Typestring
    className
    debugLogiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Display debug logs for bounce interactions.
    enableNewArchiOSAndroidHarmony
    Typeboolean·Defaulttrue on Lynx SDK >= 4.3; false otherwise
    Enable the native <scroll-view> new architecture. When enabled, bounceableOptions uses native bounces on Android, iOS, and Harmony. Defaults to true on Lynx SDK 4.3 and newer, and false on earlier versions.
    enableRTLiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Whether horizontal bounce direction should be mirrored in RTL mode.
    enableScrolliOSAndroidHarmony
    Typeboolean·Defaulttrue
    Enable scroll interaction.
    enableScrollMonitoriOSAndroidHarmony
    Typeboolean·Defaultfalse
    Enable scroll monitor.
    estimatedItemStyleiOSAndroid
    TypeCSSProperties
    Estimated height and width of the items need to be set.
    experimentalNestedScrollBackwardHarmony
    TypeselfOnly | selfFirst | parentFirst | parallel
    Adapts Harmony nested scroll behavior. 'selfOnly' scrolls only this component. 'selfFirst' scrolls this component first, then the parent after this component reaches a scroll boundary. 'parentFirst' scrolls the parent first, then this component after the parent reaches a scroll boundary. 'parallel' scrolls this component and the parent at the same time.
    experimentalNestedScrollForwardHarmony
    TypeselfOnly | selfFirst | parentFirst | parallel
    Adapts Harmony nested scroll behavior. 'selfOnly' scrolls only this component. 'selfFirst' scrolls this component first, then the parent after this component reaches a scroll boundary. 'parentFirst' scrolls the parent first, then this component after the parent reaches a scroll boundary. 'parallel' scrolls this component and the parent at the same time.
    exposureBottomiOSAndroid
    Typestring·Default'10px'
    exposure-screen-margin-bottom
    exposureIDiOSAndroidHarmony
    Typestring
    exposure-id for global exposure
    exposureLeftiOSAndroid
    Typestring·Default'10px'
    exposure-screen-margin-left
    exposureRightiOSAndroid
    Typestring·Default'10px'
    exposure-screen-margin-right
    exposureSceneiOSAndroidHarmony
    Typestring
    exposure-scene for global exposure
    exposureTopiOSAndroid
    Typestring·Default'10px'
    exposure-screen-margin-top
    firstScreenItemCountiOSAndroid
    Typenumber·Default1
    Estimated first screen item count for lazy rendering. Remaining children will complete rendering based on exposure. When this estimate is small, it may cause a blank screen phenomenon where some nodes exist on the first screen.
    horizontaliOSAndroid
    Typeboolean
    Horizontal scroll.
    iOSBouncesiOSAndroid
    Typeboolean·Defaulttrue
    Open the bouncing effect on iOS. If you want to use it on Android, please refer to the bounceableOption. If the bounceableOption is set, the iOSBounces property will be invalid.
    lazyiOSAndroid
    Typeboolean·Defaulttrue
    When enabled, only the items that are about to enter the viewport are rendered, reducing initial load time and memory usage; remaining items are rendered as they approach visibility during scroll.
    lazyOptionsiOSAndroid
    TypeLazyOptions·Defaulttrue
    When enabled, only the items that are about to enter the viewport are rendered, reducing initial load time and memory usage; remaining items are rendered as they approach visibility during scroll.
    main-thread:gestureiOSAndroid
    TypeBaseGesture<BaseGestureConfig, GestureChangeEvent>
    If you want to use gesture, pass it here.
    onUIAppeariOSAndroidHarmony
    Type(e: CommonEvent) => void
    Exposure event for UI
    onUIDisappeariOSAndroidHarmony
    Type(e: CommonEvent) => void
    Disappear event for UI
    sceneiOSAndroid
    Typestring
    Be used to mark the exposure timing of lazy loading. Please ensure that it is unique throughout the page.
    scrollMonitorTagiOSAndroidHarmony
    Typestring·Defaultfalse
    The tag for scroll monitor.
    scrollOrientationiOSAndroidHarmony
    Typevertical | horizontal·Default'vertical'
    Set to 'vertical' for vertical scrolling and set to 'horizontal' for horizontal scrolling.
    scrollPropagationBehavioriOSAndroid
    TypeScrollPropagationBehaviorOption·Default'native'
    Controls whether scroll events propagate to parent containers. For now, 'preventPropagate' needs to be used together with temporaryBlockScrollClass and temporaryBlockScrollTag on iOS.
    scrollviewIdiOSAndroid
    Typestring·Default"scrollview"
    The id of the scrollview.
    stickyiOSAndroid
    TypeReactElement<any, string | JSXElementConstructor<any>>
    Sticky item, designed for Tabs.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    temporaryBlockScrollClassiOS
    Typestring·Default'BDXLynxViewPager'
    The specific class name of the container that is blocked when 'scrollPropagationBehavior' is set to be 'preventPropagate', must be informed by the container provider. For now, 'preventPropagate' needs to be used together with temporaryBlockScrollClass and temporaryBlockScrollTag on iOS.
    temporaryBlockScrollTagiOS
    Typenumber·Default0
    Used to specify the native container tag that is blocked when 'scrollPropagationBehavior' is set to be 'preventPropagate', corresponding to the Tag attribute of UIView. Needs to be specified by the native container provider. For now, 'preventPropagate' needs to be used together with temporaryBlockScrollClass and temporaryBlockScrollTag on iOS.
    temporaryNestedScrollAndroid
    Typeboolean
    Android-only temporary flag to control nested scroll; maps to native 'enable-nested-scroll'. Android default value is true.
    testingiOSAndroid
    Typeboolean
    Testing Mode.
    Events
    catchLongPressiOSAndroidHarmony
    Type(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    Same as onLongPress, but stops the event from propagating to parent elements.
    catchTouchCanceliOSAndroidHarmony
    Type(e: TouchEvent) => void
    Same as onTouchCancel, but stops the event from propagating to parent elements.
    catchTouchEndiOSAndroidHarmony
    Type(e: TouchEvent) => void
    Same as onTouchEnd, but stops the event from propagating to parent elements.
    catchTouchMoveiOSAndroidHarmony
    Type(e: TouchEvent) => void
    Same as onTouchMove, but stops the event from propagating to parent elements.
    catchTouchStartiOSAndroidHarmony
    Type(e: TouchEvent) => void
    Same as onTouchStart, but stops the event from propagating to parent elements.
    onContentSizeChangeiOSAndroid
    Type(res: {detail: {scrollHeight: number, scrollWidth: number}}) => void
    Being triggered when scrolling content changes.
    onLayoutChangeiOSAndroidHarmony
    Type(e: EventHandler<LayoutChangeDetailEvent<Target>> | undefined) => void
    Send when UI has changed viewport size.
    onLongPressiOSAndroidHarmony
    Type(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    Send when a touch-point is held on the UI for a period of time.
    onScrolliOSAndroid
    Type(e: ScrollEvent) => void
    Being triggered when scrolling occurs.
    onScrollEndiOSAndroid
    Type(e: ScrollEndEvent) => void·Defaultundefined
    Being triggered when scrolling stops.
    onScrollToLoweriOSAndroid
    Type(e: ScrollToLowerEvent) => void·Defaultundefined
    Being triggered when scrolling to lower.
    onScrollToUpperiOSAndroid
    Type(e: ScrollToUpperEvent) => void·Defaultundefined
    Being triggered when scrolling to upper.
    onTapiOSAndroidHarmony
    Type(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
    Send when a touch-point is tapped on the UI.
    onTouchCanceliOSAndroidHarmony
    Type(e: TouchEvent) => void
    Send when a touch event is interrupted or cancelled before it is completed.
    onTouchEndiOSAndroidHarmony
    Type(e: TouchEvent) => void
    Send when a touch-point is removed from the UI.
    onTouchMoveiOSAndroidHarmony
    Type(e: TouchEvent) => void
    Send when a touch-point is moving on the UI.
    onTouchStartiOSAndroidHarmony
    Type(e: TouchEvent) => void
    Send when a touch-point is placed on the UI.
    onWheel
    Type(e: CommonEvent) => void
    Send when a wheel event is triggered on the scroll-view.

    Supporting Types

    BounceableBasicProps

    Properties
    alwaysBouncingiOSAndroidHarmony
    Typeboolean·Defaulttrue
    Whether the scrollable container can bounce when the content area of the scrollable container is smaller than the viewport area.
    enableBounceEventInFlingiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Trigger bounces effect during fling
    enableBouncesiOSAndroidHarmony
    Typeboolean
    Whether to enable bounce effect
    endBounceTriggerDistanceiOSAndroidHarmony
    Typenumber·Default0
    The threshold distance of lower bounces, in pixels, when triggering the scrollToBounces event
    estimatedHeightiOSAndroidHarmony
    Typenumber
    Unit: px. Optional size hint for bounce effect. Recommended when used in List or <list/>.
    estimatedWidthiOSAndroidHarmony
    Typenumber
    Unit: px. Optional size hint for bounce effect. Recommended when used in List or <list/>.
    lowerBounceItemiOSAndroidHarmony
    Typeany
    Content of lower bounces view, which will be displayed during the lower bouncing effect.
    singleSidedBounceiOSAndroidHarmony
    Typeupper | lower | both | iOSBounces | none·Default'both'
    The direction of the bounce effect. 'both' for bouncing on both ends, 'none' to disable bounce, and 'upper'/'lower' for bouncing on either end
    startBounceTriggerDistanceiOSAndroidHarmony
    Typenumber·Default0
    The threshold distance of upper bounces, in pixels, when triggering the scrollToBounces event
    upperBounceItemiOSAndroidHarmony
    Typeany
    Content of upper bounces view, which will be displayed during the upper bouncing effect.
    validAnimationVersioniOSAndroidHarmony
    Typeboolean·Defaultfalse
    requestAnimationFrame don't work under lynx version 2.15.2. This switch should be opened when the version is higher than 2.15.2.
    Events
    onScrollToBouncesiOSAndroidHarmony
    Type(e: ScrollToBouncesInfo) => void·Default0
    When bounces effect is triggered and the bounce distance is larger than startBounceDistance or endBounceDistance on the upper or lower side, the scrollToBounces event will be triggered.

    ScrollToBouncesInfo

    direction
    Typeupper | lower

    BounceHandlers

    main-thread:bindlayoutchange
    Type(event: CommonEvent) => void
    main-thread:bindscroll
    Type(event: ScrollEvent) => void
    main-thread:bindtouchend
    Type() => void
    main-thread:bindtouchmove
    Type(event: TouchEvent) => void
    main-thread:bindtouchstart
    Type(event: TouchEvent) => void
    onLowerDisexposure
    Type(_event: CommonEvent) => void
    onLowerExposure
    Type(_event: CommonEvent) => void
    onUpperDisexposure
    Type(_event: CommonEvent) => void
    onUpperExposure
    Type(_event: CommonEvent) => void

    How to understand properties in useBounces

    Let's see how useBounces is implemented. This hook can be attached to any scrollable container.

    Inputs and Outputs

    First, let's treat this hook as a black box that receives component settings and returns a series of methods to handle scroll container events:

    • Input: options

    • id: The scrollable container's id (required to avoid conflicts between identical containers on the same page).

    • scrollOrientation: Container scrolling direction (horizontal or vertical).

    • bounceableOptions: Additional hook configuration:

    • enableBounces: Whether to enable the bounce effect.

    • startBounceTriggerDistance/endBounceTriggerDistance: Thresholds for triggering onScrollToBounces (e.g., for "swipe-to-navigate" scenarios).

    • enableBounceEventInFling: Whether to trigger bounce effects during momentum scrolling.

    • upperBounceItem/lowerBounceItem: Content displayed in bounce areas.

    • alwaysBouncing: Enables bounce effects even when the container isn't scrollable.

    • singleSidedBounce: Restricts bounce effects to one side only.

    • onScrollToBounces: Triggered when bounce distance exceeds thresholds (filters minor bounces).

    • Output: Methods for binding to scroll containers:

    • main-thread:bindtouchstart/main-thread:bindtouchend/main-thread:bindtouchmove: Handles touch events.

    • main-thread:bindlayoutchange: Tracks container dimensions.

    • main-thread:bindscroll/main-thread:bindscrollend: Handles scroll events.

    • onUpperExposure/onUpperDisexposure/onLowerExposure/onLowerDisexposure: Manages container boundary states (bounce only occurs at edges).

    Scroll Simulation

    With enableNewArch, ScrollView uses native bounces on Android, iOS, and Harmony while retaining custom bounce items and onScrollToBounces threshold callbacks.

    On the legacy architecture, non-iOSBounces modes use MTS and transform to simulate bounce effects:

    1. Locate nodes via lynx.querySelector:
    lynx.querySelector(`#${containerID}`)
    1. Apply transform based on scroll curves from touch events:

    useBounces divides scrolling into three phases:

    1. Rubber-band effect during touchmove

    2. Momentum scrolling

    3. Bounce-back effect

    Using bounceableOptions

    enableNewArch

    ScrollView enables the native <scroll-view> new architecture by default on Lynx SDK 4.3 and newer, and keeps the legacy architecture on earlier versions. Set enableNewArch explicitly to override this version-based default.

    onScrollToBounces with distance thresholds

    This event triggers only after completed bounces, requiring:

    1. The container must be in a bounce zone at touchEnd (not in neutral area).

    2. The bounce effect must fully complete (container returns to edge). The event fires only if the maximum bounce distance exceeds the threshold.

    enableBounceEventInFling

    When enabled (default), momentum scrolling can trigger bounces if the container reaches edges mid-fling. Disable this for bounce effects that require explicit touch gestures.

    Where will upperBounceItem/lowerBounceItem show up?

    These appear exclusively in bounce zones. When unset, the translated container reveals underlying content.

    alwaysBouncing

    Forces edge detection even when the container isn't scrollable, allowing bounce effects without actual scrolling.

    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.