Swiper
A Swiper (carousel) component for ReactLynx. It provides pagination and gesture-handling primitives.You can check the source code to understand how it works, and you're welcome to submit MRs to enhance its capabilities.
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
Component API
Swiper
onSwipeStop.
This is useful for disabling clicking when swiping.onSwipeStart.
This is useful for disabling clicking when swiping.initialIndex will be used again.SwiperItem
overlap attribute applied to the view rendered by SwiperItem.
This property is used only when opacity has issues.
Refer to SwiperRef
Supporting Types
RenderFunctionProps
BounceConfig
OnBounceParams
SwipeToOptions
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
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>-2receives avalueof 0<SwiperItem>-1receives avalueof -1<SwiperItem>-3receives avalueof 1
Furthermore, when <Swiper>'s progress is updated to 3:
<SwiperItem>-2receives avalueof -1<SwiperItem>-1receives avalueof -2<SwiperItem>-3receives avalueof 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
modeConfigmode='custom' -
The position of
<SwiperItem>needs to be specified throughcustomAnimation -
Offers higher customization capabilities
To summarize:
normalmode handles the position of<SwiperItem>s, making it more suitable for horizontal sliding scenarios and easier to usecustommode 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.