Basic Usage
Use <ScrollView> to enable scrollable content.
Structure
<ScrollView>
{/* Your content */}
</ScrollView>
Component API
Properties
Typedefault | paging
Android touch recognition mode. When inside a component that supports 'paging' mode, 'paging' must be enabled.
Typeboolean
Enable bouncing effect
Typeboolean | BounceableBasicProps·Default{ enableBounces: true, singleSidedBounce: "iOSBounces" },
Props for bouncing effect
TypeReactNode
Children in scroll-view.
Typeboolean·Defaultfalse
Display debug logs for bounce interactions.
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.
Typeboolean·Defaultfalse
Whether horizontal bounce direction should be mirrored in RTL mode.
Typeboolean·Defaulttrue
Enable scroll interaction.
Typeboolean·Defaultfalse
Enable scroll monitor.
TypeCSSProperties
Estimated height and width of the items need to be set.
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.
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.
Typestring·Default'10px'
exposure-screen-margin-bottom
Typestring
exposure-id for global exposure
Typestring·Default'10px'
exposure-screen-margin-left
Typestring·Default'10px'
exposure-screen-margin-right
Typestring
exposure-scene for global exposure
Typestring·Default'10px'
exposure-screen-margin-top
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.
Typeboolean
Horizontal scroll.
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.
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.
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.
TypeBaseGesture<BaseGestureConfig, GestureChangeEvent>
If you want to use gesture, pass it here.
Type(e: CommonEvent) => void
Exposure event for UI
Type(e: CommonEvent) => void
Disappear event for UI
Typestring
Be used to mark the exposure timing of lazy loading. Please ensure that it is unique throughout the page.
Typestring·Defaultfalse
The tag for scroll monitor.
Typevertical | horizontal·Default'vertical'
Set to 'vertical' for vertical scrolling and set to 'horizontal' for horizontal scrolling.
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.
Typestring·Default"scrollview"
The id of the scrollview.
TypeReactElement<any, string | JSXElementConstructor<any>>
Sticky item, designed for Tabs.
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.
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.
Typeboolean
Android-only temporary flag to control nested scroll; maps to native 'enable-nested-scroll'. Android default value is true.
Events
Type(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
Same as onLongPress, but stops the event from propagating to parent elements.
Type(e: TouchEvent) => void
Same as onTouchCancel, but stops the event from propagating to parent elements.
Type(e: TouchEvent) => void
Same as onTouchEnd, but stops the event from propagating to parent elements.
Type(e: TouchEvent) => void
Same as onTouchMove, but stops the event from propagating to parent elements.
Type(e: TouchEvent) => void
Same as onTouchStart, but stops the event from propagating to parent elements.
Type(res: {detail: {scrollHeight: number, scrollWidth: number}}) => void
Being triggered when scrolling content changes.
Type(e: EventHandler<LayoutChangeDetailEvent<Target>> | undefined) => void
Send when UI has changed viewport size.
Type(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
Send when a touch-point is held on the UI for a period of time.
Type(e: ScrollEvent) => void
Being triggered when scrolling occurs.
Type(e: ScrollEndEvent) => void·Defaultundefined
Being triggered when scrolling stops.
Type(e: ScrollToLowerEvent) => void·Defaultundefined
Being triggered when scrolling to lower.
Type(e: ScrollToUpperEvent) => void·Defaultundefined
Being triggered when scrolling to upper.
Type(e: EventHandler<BaseTouchEvent<Target>> | undefined) => void
Send when a touch-point is tapped on the UI.
Type(e: TouchEvent) => void
Send when a touch event is interrupted or cancelled before it is completed.
Type(e: TouchEvent) => void
Send when a touch-point is removed from the UI.
Type(e: TouchEvent) => void
Send when a touch-point is moving on the UI.
Type(e: TouchEvent) => void
Send when a touch-point is placed on the UI.
Type(e: CommonEvent) => void
Send when a wheel event is triggered on the scroll-view.
Supporting Types
BounceableBasicProps
Properties
Typeboolean·Defaulttrue
Whether the scrollable container can bounce when the content area of the scrollable container is smaller than the viewport area.
Typeboolean·Defaultfalse
Trigger bounces effect during fling
Typeboolean
Whether to enable bounce effect
Typenumber·Default0
The threshold distance of lower bounces, in pixels, when triggering the scrollToBounces event
Typenumber
Unit: px. Optional size hint for bounce effect. Recommended when used in List or <list/>.
Typenumber
Unit: px. Optional size hint for bounce effect. Recommended when used in List or <list/>.
Typeany
Content of lower bounces view, which will be displayed during the lower bouncing effect.
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
Typenumber·Default0
The threshold distance of upper bounces, in pixels, when triggering the scrollToBounces event
Typeany
Content of upper bounces view, which will be displayed during the upper bouncing effect.
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
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.
BounceHandlers
Type(event: CommonEvent) => void
Type(event: ScrollEvent) => void
Type(event: TouchEvent) => void
Type(event: TouchEvent) => void
Type(_event: CommonEvent) => void
Type(_event: CommonEvent) => void
Type(_event: CommonEvent) => void
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.
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).
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:
- Locate nodes via
lynx.querySelector:
lynx.querySelector(`#${containerID}`)
- Apply
transform based on scroll curves from touch events:
useBounces divides scrolling into three phases:
-
Rubber-band effect during touchmove
-
Momentum scrolling
-
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.
This event triggers only after completed bounces, requiring:
-
The container must be in a bounce zone at touchEnd (not in neutral area).
-
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.