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

    A Swiper (carousel) component for ReactLynx. It provides pagination and gesture-handling primitives.
    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
    Advanced Usage

    Basic Usage

    Start with normal mode for common paged content. Keep the item size and container size explicit, then use onChange to sync the current index with an indicator or other page state.

    Examples

    Loop

    Use loop mode when the first and last items should connect. This avoids a hard edge in cyclic carousels such as featured content, campaigns, or repeating recommendations.

    Bounces

    Use bounce content for boundary feedback or pull-to-load behavior. Keep it hidden during normal browsing, and reveal only a lightweight state while the user drags past the edge.

    Custom

    Use a custom mode when the slide should react continuously to swipe progress. Map the progress value to transforms such as translate, scale, and rotate to build stacked-card interactions.

    You can see Advanced Usage for more.

    Structure

    <Swiper>
      {({ index }) => <SwiperItem />}
    </Swiper>

    Component API

    Swiper

    autoPlayiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Whether to enable autoPlay
    autoPlayIntervaliOSAndroidHarmony
    Typenumber·Default2000
    Auto play interval
    blockNativeEventiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Whether to block native event. Can be useful when swiper is in Scrollview, List or other components that will block swiper's touch event.
    bounceConfigiOSAndroidHarmony
    TypeBounceConfig
    BounceParams
    childreniOSAndroidHarmony
    Type(prop: {index: number, item: T, realIndex: number}) => ReactElement
    Children of Swiper should be a function, returning a SwiperItem
    consumeSlideEventiOSAndroidHarmony
    Type[number, number][]·Default[[-180, -135], [-45, 45], [135, 180]]
    Determines how swiper respond to touch in different angle. By default, swiper will only respond to horizontal touches. Refer to https://lynxjs.org/api/elements/built-in/view.html#consume-slide-event for more
    containerWidthiOSAndroidHarmony
    Typenumber·Defaultlynx.__globalProps.screenWidth ?? SystemInfo.pixelWidth / SystemInfo.pixelRatio
    Width of the Swiper viewport in px. Always pass this prop explicitly. Use the width available inside the parent. For example, inside a screen-width parent with 16px padding on each side, set containerWidth to screenWidth - 32.
    customAnimationFirstScreeniOSAndroidHarmony
    Type(value: number, index: number) => CSSProperties
    Custom animation effect used in JS, should be a JS function. customAnimationFirstScreen should be a function of the same content of 'main-thread:customAnimation' without 'main thread' annotation This is a workaround for MainThreadScript's disability for supporting firstScreen. We are working on removing the duplicated JS version of customAnimation. For now, this is needed.
    dataiOSAndroidHarmony
    TypeT[]
    Swiper items data set
    durationiOSAndroidHarmony
    Typenumber·Default500
    Duration of animation for paging or swiping
    initialIndexiOSAndroidHarmony
    Typenumber·Default0
    Initial index of Swiper, this value will only be used at firstScreen. Later updates will be ignored.
    itemHeightiOSAndroidHarmony
    Typenumber | auto
    Height of SwiperItem
    itemWidthiOSAndroidHarmony
    Typenumber
    Width of swiper item
    loopiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Swiper loop back
    loopDuplicateCountiOSAndroidHarmony
    Typenumber·Default2
    When loop is true, Swiper will duplicate the first 2 items and last 2 items to create a loop effect. This prop can be used to customize how many items to duplicate the first and last item.
    main-thread:customAnimationiOSAndroidHarmony
    Type(value: number, index: number) => CSSProperties
    Custom animation effect, should be a MainThread function
    main-thread:easingiOSAndroidHarmony
    Type(progress: number) => number
    Custom easing function for paging effect
    main-thread:onOffsetChangeiOSAndroidHarmony
    Type(offset: number) => void
    Callback fired when offset of Swiper changed. Should be a MainThread function
    offsetLimitiOSAndroidHarmony
    Type[number, number]
    Use this to limit or extend the offset of Swiper's range. This can be useful for limiting offset to avoid overscroll. For example, when mode === 'normal', and modeConfig.align === 'start', swipe to the last item technically means the last item's left edge align with container's left edge, leaving a blank area, which usually is not what we want. So we add an offsetLimit of [0, containerWidth - itemWidth], to limit the offset of Swiper. In this case, when swipe to the end, the last item's right edge align with container's right edge, leaving no blank area.
    onChangeiOSAndroidHarmony
    Type(current: number) => void
    Callback fired when currentIndex of Swiper has changed
    onSwipeStartiOSAndroidHarmony
    Type(current: number) => void
    Callback fired when swiper started to swipe. Can be used with onSwipeStop. This is useful for disabling clicking when swiping.
    onSwipeStopiOSAndroidHarmony
    Type(current: number) => void
    Callback fired when swiper stopped to swipe. Can be used with onSwipeStart. This is useful for disabling clicking when swiping.
    resetOnReuseiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Whether to reset Swiper progress and state when reuse Swiper Component. Can be useful when used in list.
    RTLiOSAndroidHarmony
    Typeboolean | lynx-rtl·Defaultfalse
    Whether to enable RTL mode.
    styleiOSAndroidHarmony
    TypeCSSProperties
    Style for the root element of the Swiper component. This controls the visible viewport/frame that contains the swiper. Use this for background, borders, border radius, and overflow. Configure dimensions through containerWidth and itemHeight, and direction through RTL. Apply outer padding and CSS classes to a surrounding view.
    swiperKeyiOSAndroidHarmony
    Typeunknown
    key of Swiper Component. Change this will reset Swiper progress and state. Can be used when reusing Swiper Component. Upon resting, initialIndex will be used again.
    trackStyleiOSAndroidHarmony
    TypeCSSProperties
    Style for the inner sliding track that holds all swiper items. This is the element that actually moves/slides.

    SwiperItem

    childreniOSAndroidHarmony
    TypeReactElement<any, string | JSXElementConstructor<any>> | ReactElement<any, string | JSXElementConstructor<any>>[]
    Children of SwiperItem
    indexiOSAndroidHarmony
    Typenumber
    Index of current SwiperItem, out of Swiper's data.
    overlapiOSAndroidHarmony
    Typeboolean
    overlap attribute applied to the view rendered by SwiperItem. This property is used only when opacity has issues. Refer to
    realIndexiOSAndroidHarmony
    Typenumber
    Physical index of current SwiperItem. Kept for compatibility with existing manual usage. This is resolved automatically when SwiperItem is rendered inside Swiper's children function.
    styleiOSAndroidHarmony
    TypeCSSProperties
    Style of SwiperItem

    SwiperRef

    cancelAnimationiOSAndroidHarmony
    Type() => void
    Cancel Current Running Animation. Use with caution, may break internal states.
    swipeNextiOSAndroidHarmony
    Type() => void
    Swiper to next item
    swipePreviOSAndroidHarmony
    Type() => void
    Swiper to previous item
    swipeToiOSAndroidHarmony
    Type(index: number, options?: {animate?: boolean, onFinished?: () => void}) => void
    SwiperTo item of index

    Supporting Types

    RenderFunctionProps

    index
    Typenumber
    Logical index of current SwiperItem in Swiper's data.
    item
    TypeT
    Data item of current SwiperItem.
    realIndex
    Typenumber
    Physical index of current SwiperItem. Kept for compatibility with existing manual SwiperItem wiring. SwiperItem receives this automatically when rendered inside Swiper's children function.

    BounceConfig

    enableiOSAndroidHarmony
    Typeboolean·Defaultfalse
    Whether to enable bounces. Ignored when loop is true.
    endBounceItemiOSAndroidHarmony
    TypeReactElement<any, string | JSXElementConstructor<any>>
    The right bounceItem (when in horizontal)
    endBounceItemWidthiOSAndroidHarmony
    Typenumber·Default50
    Width of bounceItem. When overscroll the bounces, you will have larger and larger resistance, to make overscroll not exceed bounceItemWidth
    onEndBounceItemBounceiOSAndroidHarmony
    Type(bounceParams: {offset: number, type: 'start' | 'end'}) => void
    When endBounceItem is in bounce state, releasing finger will call this.
    onStartBounceItemBounceiOSAndroidHarmony
    Type(bounceParams: {offset: number, type: 'start' | 'end'}) => void
    When startBounceItem is in bounce state, releasing finger will call this.
    startBounceItemiOSAndroidHarmony
    TypeReactElement<any, string | JSXElementConstructor<any>>
    The left bounceItem (when in horizontal)
    startBounceItemWidthiOSAndroidHarmony
    Typenumber·Default50
    Width of bounceItem. When overscroll the bounces, you will have larger and larger resistance, to make overscroll not exceed bounceItemWidth

    OnBounceParams

    offset
    Typenumber
    type
    Typestart | end

    SwipeToOptions

    animate
    Typeboolean
    onFinished
    Type() => void

    Advanced Usage

    Use the advanced APIs when the default slide layout is not enough. customAnimation lets each item respond to swipe progress, while mode decides whether Swiper places items for you or leaves placement to your animation function.

    Understanding customAnimation

    type customAnimation = (value: number, index: number) => CSSProperties

    customAnimation is a main thread function. While Swiper is scrolling, each SwiperItem receives its distance from the active item and returns the style it should use for that frame.

    The function parameter value represents the distance of this <SwiperItem> relative to the selected <SwiperItem>.

    In this example, when <Swiper>'s progress is 2:

    • <SwiperItem>-2 receives a value of 0
    • <SwiperItem>-1 receives a value of -1
    • <SwiperItem>-3 receives a value of 1

    Furthermore, when <Swiper>'s progress is updated to 3:

    • <SwiperItem>-2 receives a value of -1
    • <SwiperItem>-1 receives a value of -2
    • <SwiperItem>-3 receives a value of 0

    Use this value as a stable input for interpolation. For example, 0 is the active item, -1 is the previous item, and 1 is the next item.

    Practice with customAnimation

    This pattern is useful when Swiper should keep its normal layout but the items need visual treatment such as scale, opacity, or rotation.

    Understanding mode

    <Swiper> supports two mode options: normal and custom. Their differences are as follows:

    mode='normal'

    • <SwiperItem>s are arranged sequentially in the direction

    • Provides center alignment, right alignment, and other capabilities through modeConfig mode='custom'

    • The position of <SwiperItem> needs to be specified through customAnimation

    • Offers higher customization capabilities

    To summarize:

    • normal mode handles the position of <SwiperItem>s, making it more suitable for horizontal sliding scenarios and easier to use
    • custom mode requires manual position calculation but offers higher extensibility

    Practice with customAnimation when mode='custom'

    Use custom mode when item placement itself is part of the design. In this mode, the animation function should return both position and visual style.

    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.