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

    A virtualized List component for ReactLynx. Designed to render long lists of data.
    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

    Structure

    <List>
      <list-item />
    </List>

    Component API

    List

    Properties
    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.
    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
    TypeListItemSnapAlignment
    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.
    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.
    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<ListRef>
    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: LayoutCompleteEvent) => 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.

    ListRef

    autoScrolliOSAndroidHarmony
    Type(rate: px | rpx | ppx | rem | em | vw | vh, start: boolean, autoStop: boolean) => void
    Scroll the list to the specified position and offset.
    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.

    Supporting Types

    DiffResultDetails

    insertions
    Typenumber[]
    move_from
    Typenumber[]
    move_to
    Typenumber[]
    removals
    Typenumber[]
    update_from
    Typenumber[]
    update_to
    Typenumber[]

    LayoutCompleteEvent

    detailiOSAndroidHarmony
    TypeLayoutCompleteEventDetail
    Layout details.

    LayoutCompleteEventDetail

    diffResult
    TypeDiffResultDetails
    layout-idiOSAndroidHarmony
    Typenumber
    Connected to a setState.
    visibleCellsAfterLayout
    TypeListItemInfo[]
    visibleCellsBeforeLayout
    TypeListItemInfo[]

    ListItemInfo

    height
    Typenumber
    isBinding
    Typeboolean
    itemKey
    Typestring
    originX
    Typenumber
    originY
    Typenumber
    updated
    Typeboolean
    width
    Typenumber

    ListItemSnapAlignment

    factoriOSAndroidHarmony
    Typenumber
    Anchoring the position in pagination, with a value range of [0, 1]. 0 - the scrolling List child node aligns with the top of the List. 1 - the scrolling List child node aligns with the bottom of the List.
    offsetiOSAndroidHarmony
    Typenumber
    Add an additional offset parameter to apply an extra offset on top of the factor.
    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.