> For AI agents: the complete documentation index is available at /next/llms.txt, the full documentation bundle is available at /next/llms-full.txt.

# 

# Swiper

A Swiper (carousel) component for ReactLynx. It provides pagination and gesture-handling primitives.
:::info

You can check the [source code](https://github.com/lynx-family/lynx-ui/tree/main/packages/lynx-ui-swiper) to understand how it works, and you're welcome to submit MRs to enhance its capabilities.

:::


**Basic 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.


**This is an example below: lynx-ui-swiper**

**Entry:** `Basic`
**Bundle:** `dist/SwiperBasic.lynx.bundle` | Web: `dist/SwiperBasic.web.bundle`

```tsx {33-46,63-66}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useRef, useState } from '@lynx-js/react'

import { Swiper, SwiperItem } from '@lynx-js/lynx-ui'
import type { SwiperRef } from '@lynx-js/lynx-ui'

import { Button } from '../Common/Button'
import { Card } from '../Common/Card'
import { Indicator } from '../Common/Indicator'

import './styles.css'

const itemArr: number[] = [1, 2, 3, 4, 5]

const itemWidths = [250, 350, 400]
const alignArr: ['start', 'center', 'end'] = ['start', 'center', 'end']

const INITIAL_INDEX = 2

function SwiperEntry(): JSX.Element {
  const [itemWidthsIndex, setItemWidthsIndex] = useState<number>(0)
  const [alignIndex, setAlignIndex] = useState<number>(1)
  const [currentIndex, setCurrentIndex] = useState<number>(INITIAL_INDEX)
  const swiperRef = useRef<SwiperRef>(null)

  return (
    <view className='demo-container lunaris-dark'>
      <view className='top-area' />
      <view className='content-area'>
        <Swiper
          ref={swiperRef}
          data={itemArr}
          itemWidth={itemWidths[itemWidthsIndex] ?? 0}
          containerWidth={lynx.__globalProps.screenWidth - 32
            || SystemInfo.pixelWidth / SystemInfo.pixelRatio - 32}
          duration={500}
          initialIndex={INITIAL_INDEX}
          onChange={setCurrentIndex}
          mode='normal'
          modeConfig={{
            align: alignArr[alignIndex],
            spaceBetween: 16,
          }}
          autoPlay={false}
          style={{
            overflow: 'visible',
          }}
        >
          {({ index }) => (
            <SwiperItem>
              <Card
                index={index}
                style={{
                  height: '250px',
                }}
              />
            </SwiperItem>
          )}
        </Swiper>
        <Indicator
          current={currentIndex}
          count={itemArr.length}
        />
      </view>
      <view className='operation'>
        <Button
          onClick={() => {
            swiperRef.current?.swipePrev()
          }}
          className='expand'
          text='SwipePrev'
        />
        <Button
          onClick={() => {
            swiperRef.current?.swipeNext()
          }}
          className='expand'
          type='primary'
          text='SwipeNext'
        />
      </view>
      <view className='sub-operation'>
        <Button
          onClick={() => {
            setItemWidthsIndex(prev => (prev + 1) % itemWidths.length)
          }}
          text={'Change Item Width'}
          subText={`ItemWidth: ${itemWidths[itemWidthsIndex]}`}
        >
        </Button>
        <Button
          onClick={() => {
            setAlignIndex(prev => (prev + 1) % itemWidths.length)
          }}
          text={'Change Align Type'}
          subText={`AlignType: ${alignArr[alignIndex]}`}
        >
        </Button>
      </view>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```



## 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.


**This is an example below: lynx-ui-swiper**

**Entry:** `Loop`
**Bundle:** `dist/SwiperLoop.lynx.bundle` | Web: `dist/SwiperLoop.web.bundle`

```tsx {34-48}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { Swiper, SwiperItem } from '@lynx-js/lynx-ui'

import { Card } from '../Common/Card'
import { Indicator } from '../Common/Indicator'

import '../Common/Demo/styles.css'

const itemArr: number[] = [1, 2, 3, 4]

function SwiperEntry() {
  const [currentIndex, setCurrentIndex] = useState(0)
  const SwiperItemGap = 8
  const screenWidth = lynx.__globalProps.screenWidth
    ?? SystemInfo.pixelWidth / SystemInfo.pixelRatio
  const containWidth = (screenWidth || 375) - SwiperItemGap * 2
  const itemWidth = ((screenWidth || 375) / 375) * 315

  console.log(
    'screenWidth, itemWidth, containWidth',
    screenWidth,
    itemWidth,
    containWidth,
  )
  return (
    <view className='demo-container lunaris-dark'>
      <view className='top-area' />
      <view className='content-area'>
        <Swiper
          data={itemArr}
          itemWidth={itemWidth + SwiperItemGap}
          itemHeight={250}
          containerWidth={containWidth}
          loop={true}
          duration={500}
          initialIndex={0}
          mode='normal'
          modeConfig={{
            spaceBetween: SwiperItemGap,
          }}
          autoPlay={true}
          onChange={setCurrentIndex}
          experimentalHorizontalSwipeOnly={true}
          style={{
            overflow: 'visible',
          }}
        >
          {({ index }) => (
            <SwiperItem>
              <Card
                index={index}
                style={{
                  height: '250px',
                }}
              />
            </SwiperItem>
          )}
        </Swiper>
        <Indicator
          current={currentIndex}
          count={itemArr.length}
        />
      </view>
      <view className='demo-status'>
        <text className='demo-status-text'>
          Loop mode keeps autoplay continuous across the boundary.
        </text>
      </view>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```



### 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.


**This is an example below: lynx-ui-swiper**

**Entry:** `Bounces`
**Bundle:** `dist/SwiperBounces.lynx.bundle` | Web: `dist/SwiperBounces.web.bundle`

```tsx {43-64}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useState } from '@lynx-js/react'

import { Swiper, SwiperItem } from '@lynx-js/lynx-ui'

import { Card } from '../Common/Card'
import { Indicator } from '../Common/Indicator'

import '../Common/Demo/styles.css'
import './styles.css'

const itemArr: number[] = [1, 2, 3, 4]
const CONTAINER_PADDING = 32
const BOUNCE_WIDTH = 96
const ITEM_GAP = 16
const ITEM_HEIGHT = 220

const getScreenWidth = () =>
  lynx.__globalProps.screenWidth
  || SystemInfo.pixelWidth / SystemInfo.pixelRatio

function SwiperEntry() {
  const [currentIndex, setCurrentIndex] = useState(0)
  const containerWidth = getScreenWidth() - CONTAINER_PADDING
  const itemWidth = Math.min(300, containerWidth - 48)

  return (
    <view className='demo-container lunaris-dark'>
      <view className='top-area' />
      <view className='content-area bounces-content-area'>
        <Swiper
          data={itemArr}
          itemWidth={itemWidth}
          itemHeight={ITEM_HEIGHT}
          containerWidth={containerWidth}
          loop={false}
          duration={500}
          initialIndex={2}
          mode='normal'
          modeConfig={{
            align: 'start',
            spaceBetween: ITEM_GAP,
          }}
          style={{
            overflow: 'hidden',
          }}
          bounceConfig={{
            enable: true,
            startBounceItemWidth: 0,
            endBounceItemWidth: BOUNCE_WIDTH,
            endBounceItem: (
              <view className='bounce-loading'>
                <view className='bounce-loading-dot bounce-loading-dot--first' />
                <view className='bounce-loading-dot bounce-loading-dot--second' />
                <view className='bounce-loading-dot bounce-loading-dot--third' />
              </view>
            ),
            onEndBounceItemBounce: ({ type }) => {
              console.log('onBounce result', type)
            },
          }}
          onChange={setCurrentIndex}
        >
          {({ index }) => (
            <SwiperItem>
              <Card
                index={index}
                style={{
                  height: `${ITEM_HEIGHT}px`,
                }}
              />
            </SwiperItem>
          )}
        </Swiper>
        <Indicator
          current={currentIndex}
          count={itemArr.length}
        />
      </view>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```



### 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](/next/ui/components/swiper.md?page=1) for more.


**This is an example below: lynx-ui-swiper**

**Entry:** `CustomTinder`
**Bundle:** `dist/SwiperCustomTinder.lynx.bundle` | Web: `dist/SwiperCustomTinder.web.bundle`

```tsx {22-35,81-83}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root } from '@lynx-js/react'

import {
  Swiper,
  SwiperItem,
  interpolate,
  interpolateJS,
} from '@lynx-js/lynx-ui'

import { Card } from './Card'

import './styles.css'

const itemArr: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
const ITEM_WIDTH = 220
const ITEM_HEIGHT = 330

const customAnimation = (value: number) => {
  'main thread'
  const translateX = interpolate(value, [-1, 0], [-ITEM_WIDTH, 0], 'clamp')
  const translateY = interpolate(value, [0, 1], [0, -18], 'extend')
  const rotate = interpolate(value, [-1, 0], [-15, 0], 'clamp')
  const scale = interpolate(value, [0, 1], [1, 0.95], 'extend')
  const opacity = interpolate(value, [-1, -0.8, 0, 1], [0, 0.9, 1, 1], 'clamp')

  return {
    transform:
      `translate(${translateX}px, ${translateY}px) rotateZ(${rotate}deg) scale(${scale})`,
    opacity: opacity,
    'transform-origin': 'center',
  }
}

const customAnimationFirstScreen = (value: number, _index: number) => {
  const translateX = interpolateJS(value, [-1, 0], [-ITEM_WIDTH, 0], 'clamp')
  const translateY = interpolateJS(value, [0, 1], [0, -18], 'extend')
  const rotate = interpolateJS(value, [-1, 0], [-15, 0], 'clamp')
  const zIndex = interpolateJS(
    value,
    itemArr.map((_, index) => index),
    itemArr.map((_, index) => (itemArr.length - index) * 10),
    'extend',
  )

  const scale = interpolateJS(
    value,
    [0, 1, 0],
    [1, 0.95, 1],
    'extend',
  )
  const opacity = interpolateJS(
    value,
    [-1, -0.8, 0, 1],
    [0, 0.9, 1, 1],
    'clamp',
  )

  return {
    transform:
      `translate(${translateX}px, ${translateY}px) rotateZ(${rotate}deg) scale(${scale})`,
    opacity: opacity,
    'transform-origin': 'center',
    zIndex: zIndex,
  }
}

function SwiperEntry() {
  return (
    <view className='demo-container lunaris-dark'>
      <Swiper
        data={itemArr}
        itemWidth={ITEM_WIDTH}
        itemHeight={ITEM_HEIGHT}
        containerWidth={ITEM_WIDTH}
        duration={500}
        initialIndex={0}
        mode='custom'
        main-thread:customAnimation={customAnimation}
        customAnimationFirstScreen={customAnimationFirstScreen}
        style={{
          overflow: 'visible',
        }}
      >
        {({ index }) => (
          <SwiperItem>
            <view
              class='block-view'
              style={{
                width: '100%',
                height: '100%',
                display: 'flex',
                justifyContent: 'center',
                alignItems: 'center',
              }}
            >
              <Card index={index} />
            </view>
          </SwiperItem>
        )}
      </Swiper>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```



## Structure


```tsx
<Swiper>
  {({ index }) => <SwiperItem />}
</Swiper>
```
## Component API \{#api}

### Swiper \{#api-swiper}


### SwiperItem \{#api-swiper-item}


### SwiperRef \{#api-swiper-ref}


## Supporting Types \{#api-supporting-types}

### RenderFunctionProps \{#api-supporting-types-render-function-props}


### BounceConfig \{#api-supporting-types-bounce-config}


### OnBounceParams \{#api-supporting-types-on-bounce-params}


### SwipeToOptions \{#api-supporting-types-swipe-to-options}

**Advanced Usage**

## 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.


**This is an example below: lynx-ui-swiper**

**Entry:** `Custom`
**Bundle:** `dist/SwiperCustom.lynx.bundle` | Web: `dist/SwiperCustom.web.bundle`

```tsx {22-44,54-70}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useRef, useState } from '@lynx-js/react'

import {
  Swiper,
  SwiperItem,
  interpolate,
  interpolateJS,
} from '@lynx-js/lynx-ui'
import type { SwiperRef } from '@lynx-js/lynx-ui'

import { Card } from '../Common/Card'
import { Indicator } from '../Common/Indicator'

import '../Common/Demo/styles.css'

const itemArr: number[] = [1, 2, 3, 4, 5]

function customAnimation(value: number, _index: number) {
  'main thread'

  const scale = interpolate(value, [-1, 0, 1], [0.5, 1, 0.5])

  return {
    transform: `scale(${scale})`,
  }
}

function customAnimationFirstScreen(value: number, _index: number) {
  const scale = interpolateJS(value, [-1, 0, 1], [0.5, 1, 0.5])

  return {
    transform: `scale(${scale})`,
  }
}

function SwiperEntry(): JSX.Element {
  const swiperRef = useRef<SwiperRef>(null)
  const [currentIndex, setCurrentIndex] = useState(0)

  return (
    <view className='demo-container lunaris-dark'>
      <view className='top-area' />
      <view className='content-area'>
        <Swiper
          ref={swiperRef}
          data={itemArr}
          itemWidth={250}
          duration={500}
          initialIndex={0}
          mode='normal'
          modeConfig={{
            align: 'center',
          }}
          onChange={setCurrentIndex}
          main-thread:customAnimation={customAnimation}
          customAnimationFirstScreen={customAnimationFirstScreen}
          style={{
            overflow: 'visible',
          }}
        >
          {({ index }) => (
            <SwiperItem>
              <Card
                index={index}
                style={{
                  height: '250px',
                }}
              />
            </SwiperItem>
          )}
        </Swiper>
        <Indicator current={currentIndex} count={itemArr.length} />
      </view>
      <view className='demo-status'>
        <text className='demo-status-text'>
          Custom animation scales each slide around the active item.
        </text>
      </view>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```



## 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`](#understanding-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.


**This is an example below: lynx-ui-swiper**

**Entry:** `CustomScale`
**Bundle:** `dist/SwiperCustomScale.lynx.bundle` | Web: `dist/SwiperCustomScale.web.bundle`

```tsx {25-60,71-81}
// Copyright 2026 The Lynx Authors. All rights reserved.
// Licensed under the Apache License Version 2.0 that can be found in the
// LICENSE file in the root directory of this source tree.

import { root, useRef, useState } from '@lynx-js/react'

import {
  Swiper,
  SwiperItem,
  interpolate,
  interpolateJS,
} from '@lynx-js/lynx-ui'
import type { SwiperRef } from '@lynx-js/lynx-ui'

import { Card } from '../Common/Card'
import { Indicator } from '../Common/Indicator'

import '../Common/Demo/styles.css'

const itemArr: number[] = [1, 2, 3, 4, 5]

const ITEM_WIDTH = 250

function customAnimation(value: number, _index: number) {
  'main thread'

  const scale = interpolate(value, [-1, 0, 1], [0.8, 1, 0.8])
  // const scale = 1

  const centerOffset = ((lynx.__globalProps.screenWidth
    ?? SystemInfo.pixelWidth / SystemInfo.pixelRatio) - ITEM_WIDTH) / 2
  const translateX = interpolate(value, [-1, 0, 1], [
    -ITEM_WIDTH + centerOffset,
    centerOffset,
    ITEM_WIDTH + centerOffset,
  ], 'extend')

  return {
    transform: `translateX(${translateX}px) scale(${scale})`,
    'transform-origin': 'center',
  }
}

function customAnimationFirstScreen(value: number, _index: number) {
  const scale = interpolateJS(value, [-1, 0, 1], [0.8, 1, 0.8])
  // const scale = 1
  const centerOffset = ((lynx.__globalProps.screenWidth
    ?? SystemInfo.pixelWidth / SystemInfo.pixelRatio) - ITEM_WIDTH) / 2
  const translateX = interpolateJS(value, [-1, 0, 1], [
    -ITEM_WIDTH + centerOffset,
    centerOffset,
    ITEM_WIDTH + centerOffset,
  ], 'extend')

  console.log(
    'customAnimationFirstScreen',
    value,
    scale,
    translateX,
    centerOffset,
  )
  return {
    transform: `translateX(${translateX}px) scale(${scale})`,
    'transform-origin': 'center',
  }
}

function SwiperEntry(): JSX.Element {
  const swiperRef = useRef<SwiperRef>(null)
  const [currentIndex, setCurrentIndex] = useState(0)

  return (
    <view className='demo-container lunaris-dark'>
      <view className='top-area' />
      <view className='content-area'>
        <Swiper
          ref={swiperRef}
          data={itemArr}
          itemWidth={ITEM_WIDTH}
          itemHeight={250}
          duration={500}
          initialIndex={0}
          mode='custom'
          modeConfig={{
            align: 'center',
          }}
          onChange={setCurrentIndex}
          main-thread:customAnimation={customAnimation}
          customAnimationFirstScreen={customAnimationFirstScreen}
          style={{
            overflow: 'visible',
          }}
        >
          {({ index }) => (
            <SwiperItem>
              <Card
                index={index}
                style={{
                  height: '250px',
                }}
              />
            </SwiperItem>
          )}
        </Swiper>
        <Indicator current={currentIndex} count={itemArr.length} />
      </view>
      <view className='demo-status'>
        <text className='demo-status-text'>
          Custom mode keeps the active slide centered while scaling neighbors.
        </text>
      </view>
    </view>
  )
}

root.render(<SwiperEntry />)

export default SwiperEntry

```


