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.
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.
SwiperProps
Typeboolean·Defaultfalse
Whether to enable autoPlay
Typenumber·Default2000
Auto play interval
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.
TypeBounceConfig
BounceParams
Type(prop: {index: number, item: T, realIndex: number}) => ReactElement
Children of Swiper should be a function, returning a SwiperItem
Typeundefined[]·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
Typenumber·Defaultlynx.__globalProps.screenWidth
Width of swiper item
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.
TypeT[]
Swiper items data set
Typenumber·Default500
Duration of animation for paging or swiping
Typenumber·Default0
Initial index of Swiper, this value will only be used at firstScreen. Later updates will be ignored.
Typenumber | auto
Height of SwiperItem
Typenumber
Width of swiper item
Typeboolean·Defaultfalse
Swiper loop back
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.
Type(value: number, index: number) => CSSProperties
Custom animation effect, should be a MainThread function
Type(progress: number) => number
Custom easing function for paging effect
Type(offset: number) => void
Callback fired when offset of Swiper changed.
Should be a MainThread function
Type[object Object]
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.
Type(current: number) => void
Callback fired when currentIndex of Swiper has changed
Type(current: number) => void
Callback fired when swiper started to swipe. Can be used with onSwipeStop.
This is useful for disabling clicking when swiping.
Type(current: number) => void
Callback fired when swiper stopped to swipe. Can be used with onSwipeStart.
This is useful for disabling clicking when swiping.
Typeboolean·Defaultfalse
Whether to reset Swiper progress and state when reuse Swiper Component.
Can be useful when used in list.
Typeboolean | lynx-rtl·Defaultfalse
Whether to enable RTL mode.
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, padding, dimensions, overflow, etc.
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.
TypeCSSProperties
Style for the inner sliding track that holds all swiper items.
This is the element that actually moves/slides.
RenderFunctionProps
Typenumber
Logical index of current SwiperItem in Swiper's data.
TypeT
Data item of current SwiperItem.
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
Typeboolean·Defaultfalse
Whether to enable bounces. Ignored when loop is true.
TypeReactElement
The right bounceItem (when in horizontal)
Typenumber·Default100
Width of bounceItem.
When overscroll the bounces, you will have larger and larger resistance, to make overscroll not exceed bounceItemWidth
Type(bounceParams: {offset: number, type: start | end}) => void
····· ··
When endBounceItem is in bounce state, releasing finger will call this.
Type(bounceParams: {offset: number, type: start | end}) => void
When startBounceItem is in bounce state, releasing finger will call this.
TypeReactElement
The left bounceItem (when in horizontal)
Typenumber·Default100
Width of bounceItem.
When overscroll the bounces, you will have larger and larger resistance, to make overscroll not exceed bounceItemWidth
onBounceParams
SwipeToOptions
SwiperRef
Type() => void
Cancel Current Running Animation.
Use with caution, may break internal states.
Type() => void
Swiper to next item
Type() => void
Swiper to previous item
Type(index: number, options: {animate?: boolean, onFinished?: () => void}) => void
SwiperTo item of index
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 usecustom 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.
