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/feed-list.md.
lynx-ui logo
lynx-ui
  • English
  • FeedList

    A FeedList component for ReactLynx. Designed to render lists with complex layouts and infinite scrolling.
    Info

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

    Moreover, you can also implement your own feed/list interaction behavior with MTS.

    Basic Usage
    Under the `refreshOptions`

    Basic Usage

    Use FeedList when the page needs both virtualized list rendering and feed behaviors such as pull-to-refresh or load-more. Keep each row as a direct list-item child with a stable item-key, and provide listId plus listType so the underlying list can manage identity and layout.

    Examples

    Use loadMoreFooter for the loading state and noMoreDataFooter when the feed has reached the end. Switch between them through changeHasMoreStatus; this footer state is independent from refresh state and list diff results.

    How to trigger refresh directly

    Use startRefresh when refresh should be driven by a command instead of a pull gesture, such as a retry button or external filter change. After the data request finishes, call finishRefresh to release the refresh header.

    Structure

    <FeedList>
      <list-item />
    </FeedList>

    Component API

    FeedList

    Properties
    bounceableOptionsiOSAndroid
    Typeboolean | BounceableBasicProps·Defaultfalse
    Accept true for default options. If you need to customize the bounceable effect, you can pass in the bounceableProps.
    bouncesiOS
    Typeboolean·Defaulttrue
    Enable iOS bounces effect.
    childreniOSAndroidHarmony
    TypeReactNode
    Children of list.
    classNameiOSAndroidHarmony
    Typestring
    className
    crossAxisGapiOSAndroidHarmony
    Typenumber·Default0
    Specifies the cross axis spacing between Component in the list.
    debugLogiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Enable debug logs for refresh and bounce lifecycle.
    enableRTLiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Whether horizontal bounce direction should be mirrored in RTL mode.
    enableScrolliOSAndroidHarmony
    Typeboolean·Defaulttrue
    Enable vertical scroll.
    enableScrollBariOSAndroidHarmony
    Typeboolean·Defaultfalse
    Enable scrollBar.
    enableScrollMonitoriOSAndroidHarmony
    Typeboolean·Defaultfalse
    Enable scroll monitor.
    exposureIDiOSAndroidHarmony
    Typestring
    exposure-id for global exposure
    exposureSceneiOSAndroidHarmony
    Typestring
    exposure-scene for global exposure
    initialScrollIndexiOSAndroidHarmony
    Typenumber·Default0
    The position to which the list automatically scrolls on the initial load.
    iosEnableSimultaneousTouchiOS
    Typeboolean·Defaulttrue
    Force touch event to send to List.
    iosScrollsToTopiOS
    Typeboolean·Defaulttrue
    Whether tapping the iOS status bar should scroll to top.
    itemSnapiOSAndroidHarmony
    Type{factor: number, offset: number}
    Paginated scrolling effects
    listIdiOSAndroidHarmony
    Typestring
    The id of the list.
    listMaxSizeiOSAndroidHarmony
    Typenumber
    Unit is px. Sets the auto-limiting size for the container. When child content size is below this value,the container size adjusts to fit content. When exceeded, the container locks at this size.
    listPropsiOSAndroidHarmony
    TypeListProps
    Original list props to spread directly onto the underlying list element. This is an escape hatch for platform or engine attributes that are not yet covered by ListProps.
    listTypeiOSAndroidHarmony
    Typesingle | flow | waterfall
    The layout type of list.
    loadMoreFooteriOSAndroid
    TypeReactElement<any, string | JSXElementConstructor<any>>·Defaultfalse
    The loadmore area of the list.
    lowerThresholdItemCountiOSAndroidHarmony
    Typenumber·Default0
    Will override the lower-threshold. The item threshold from the lower edge of the list to trigger the onScrollToLower event.
    main-thread:gestureiOSAndroid
    TypeBaseGesture<BaseGestureConfig, GestureChangeEvent>
    If you want to use gesture, pass it here.
    mainAxisGapiOSAndroidHarmony
    Typenumber·Default0
    Specifies the major axis spacing between Component in the list.
    nameiOSAndroidHarmony
    Typestring
    The name of list.
    needLayoutCompleteInfoiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Output layout complete detailed info.
    noMoreDataFooteriOSAndroid
    TypeReactElement<any, string | JSXElementConstructor<any>>·Defaultfalse
    When no more data to be inserted and the hasMoreData method is called, the loadMoreFooter will be switched to noMoreDataFooter.
    onUIAppeariOSAndroidHarmony
    Type(e: CommonEvent) => void
    Exposure event for UI
    onUIDisappeariOSAndroidHarmony
    Type(e: CommonEvent) => void
    Disappear event for UI
    preloadBufferCountiOSAndroidHarmony
    Typenumber·Default0
    Controls the number of nodes to be preloaded outside the on-screen nodes of the list. Not supported when listType is set to 'waterfall'.
    ref
    TypeForwardedRef<FeedListRef>
    refreshOptionsiOSAndroid
    Typeboolean | RefreshProps·Defaultfalse
    Accept true for default options. Pass RefreshProps to customize the refresh effect or select the native implementation with mode: 'native'.
    scrollEventThrottleiOSAndroidHarmony
    Typenumber·Default200
    The time interval, in milliseconds, for the list to trigger the scroll event callback.
    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
    TypeScrollPropagationBehavior·Default'native'
    Controls whether scroll events propagate to parent containers. For now, 'preventPropagate' needs to be used together with temporaryBlockScrollClass and temporaryBlockScrollTag on iOS.
    shouldRequestStateRestoreiOSAndroidHarmony
    Typeboolean·Defaultfalse
    The lifecycle of element layer reuse. It solves the problem of reuse status disorder in the UI layer.
    showVisibleItemInfoInScrollEventiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Controls whether the attachedCells information is included in the bindScroll event detail.
    spanCountiOSAndroidHarmony
    Typenumber·Defaulttrue
    The span count of list.
    stickyOffsetiOSAndroidHarmony
    Typenumber·Default0
    The offset of the sticky position from the top or bottom of the list.
    styleiOSAndroidHarmony
    TypeCSSProperties
    style
    temporaryAndroidEnableOverflowAndroid
    Typeboolean·Defaulttrue
    Used to control whether platform list enable overflow property on Android platform.
    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. This is a temporary props and will be deprecated on new Lynx SDK version.
    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. This is a temporary props and will be deprecated on new Lynx SDK version.
    upperThresholdItemCountiOSAndroidHarmony
    Typenumber·Default0
    Will override the upper-threshold. The item threshold from the upper edge of the list to trigger the onScrollToUpper event.
    useRefactorListiOSAndroidHarmony
    Typeboolean·Defaulttrue
    Use refactored list.
    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.
    debugLogLeveliOSAndroidHarmony
    Type0 | 1 | 2 | 3·Default0
    Display debug logs. 0: none, 1: error, 2: info, 3: verbose
    onLayoutChangeiOSAndroidHarmony
    Type(e: EventHandler<LayoutChangeDetailEvent<Target>> | undefined) => void
    Send when UI has changed viewport size.
    onLayoutCompleteiOSAndroidHarmony
    Type(e: {detail: LayoutCompleteEventDetail}) => void
    Send when list's items are updated and this update process has finished.
    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.
    onScrollStateChangeiOSAndroidHarmony
    Type(e: ListScrollStateChangeEvent) => void
    The scroll state change.
    onScrollToLoweriOSAndroid
    Type(e: ScrollToLowerEvent) => void·Defaultundefined
    Being triggered when scrolling to lower.
    onScrollToUpperiOSAndroid
    Type(e: ScrollToUpperEvent) => void·Defaultundefined
    Being triggered when scrolling to upper.
    onSnapToItemiOSAndroidHarmony
    Type(e: ListSnapEvent) => void
    Send when list snaps to an item.
    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 list.

    FeedListRef

    autoScrolliOSAndroidHarmony
    Type(rate: px | rpx | ppx | rem | em | vw | vh, start: boolean, autoStop: boolean) => void
    Scroll the list to the specified position and offset.
    changeHasMoreStatusiOSAndroid
    Type(hasMore: boolean) => void
    When no more data has to be inserted, call this method to replace loadMoreFooter to noMoreDataFooter.
    finishRefreshiOSAndroid
    Type() => void
    After the startrefresh event, calling this method will end the refresh state and make the refreshHeader bounces hack.
    getVisibleCellsiOSAndroidHarmony
    Type(success?: (res: unknown) => void, fail?: (res: unknown) => void) => void
    Scroll the list to the specified position and offset.
    scrollIntoIDiOSAndroidHarmony
    Type(animated: boolean, alignTo: top | bottom | middle | none, listItemID: string, id: string, index: number, offset?: number, success?: (res: unknown) => void, fail?: (res: unknown) => void) => void
    Extends standard list's scrollTo. This method uses worklet and supports parameter id like 'scrollIntoView' method for scroll-view. As list is lazy, index is necessary in this method to find where id's component located. useRefactorList={true} is required
    scrollToiOSAndroidHarmony
    Type(animated: boolean, alignTo: top | bottom | middle | none, index?: number, offset?: number, success?: (res: unknown) => void, fail?: (res: unknown) => void) => void
    Scroll the list to the specified position and offset.
    startRefreshiOSAndroid
    Type() => void
    When enable-refresh is true, calling this function causes the refreshHeader to be fully exposed, triggering the startrefresh event. Afterwards, refreshHeader is attached to the top of List.

    Supporting Types

    BounceableBasicProps

    alwaysBouncing
    Typeboolean
    enableBounceEventInFling
    Typeboolean
    enableBounces
    Typeboolean
    endBounceTriggerDistance
    Typenumber
    estimatedHeight
    Typenumber
    estimatedWidth
    Typenumber
    lowerBounceItem
    TypeReactElement<any, string | JSXElementConstructor<any>>
    onScrollToBounces
    Type(e: {direction: upper | lower}) => void
    singleSidedBounce
    Typenone | upper | lower | both | iOSBounces
    startBounceTriggerDistance
    Typenumber
    upperBounceItem
    TypeReactElement<any, string | JSXElementConstructor<any>>
    validAnimationVersion
    Typeboolean

    RefreshProps

    enableRefresh
    Typeboolean
    headerContent
    Typeany
    mode
    Typenative | hook·Default'hook'
    Select the pull-to-refresh implementation. hook uses useRefreshAndBounce; native uses the platform <refresh> element. Native mode only supports vertical lists.
    onHeaderReleased
    Type(e: {headerSize: number, offset: number}) => void
    onRefreshOffsetChange
    Type(e: {headerSize: number, isDragging: boolean, offset: number}) => void
    onRefreshStateChange
    Type(e: {state: number}) => void
    onStartRefresh
    Type(e: {triggeredBy: startRefresh | drag}) => void
    validAnimationVersion
    Typeboolean

    UseRefreshAndBounceReturn

    finishRefresh
    Type() => void
    main-thread:onLayoutChange
    Type(e: LayoutChangeEvent) => void
    main-thread:onLayoutComplete
    Type() => void
    main-thread:onScroll
    Type(e: ScrollEvent) => void
    onLowerDisexposure
    Type() => void
    onLowerExposure
    Type() => void
    onRefreshHeaderLayoutUpdated
    Type(e: LayoutChangeEvent) => void
    onUpperDisexposure
    Type() => void
    onUpperExposure
    Type() => void
    refreshAndBounceGesture
    TypeNativeGesture
    startRefreshMethod
    Type() => void

    How to Use refreshOptions

    The useRefresh hook extends the useBounces hook, leveraging its core functionality while adding several key capabilities:

    • Supports a dedicated refreshHeader node (counterpart to upperBounceItem)

    • Enables pause behavior at the refreshHeader position to simulate pull-to-refresh effects

    We modified rebound curve to pause at the refreshHeader boundary (refresh zone edge), remaining there until manually released via finishRefresh after data loading completes.

    A complete refresh consists of four distinct phases, and the events below map to those transitions.

    Events

    Each phase triggers specific events:

    • onStartRefresh: The key event in phase 3 for initiating data updates.

    • onRefreshOffsetChange: Continuously fires while refreshHeader is visible, reporting its exposure percentage

    • onHeaderReleased: Triggers when releasing drag after phase 2 (beginning rebound to refreshHeader)

    • onRefreshStateChange: Fires during phase transitions, providing full state tracking:

      • IDLE: Default state (refreshHeader hidden)

      • OVER_DRAG_RELEASE: Matches onHeaderReleased timing (post-drag release)

      • REFRESHING: Matches onStartRefresh timing

      • DRAGGING: Continuous state while dragging with refreshHeader exposed

    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.