---
name: "Swiper"
mode: "component"
versionRequirements:
  - { name: "@ray-js/ray", version: "0.5.10" }
title: "Swiper - Slideshow and carousel container, overall height must be specified"
---

## Swiper

> [VERSION] @ray-js/ray >= 0.5.10

### Description

Slider/Carousel container supporting automatic switching, seamless swiping, and indicator dots; requires an explicit overall height.

### Props

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `dots` | `boolean` | No | `false` | Whether to show indicator dots |
| `dotColor` | `string` | No | `"rgba(0,0,0,0.3)"` | Indicator dot color |
| `dotActiveColor` | `string` | No | `"#000"` | Active indicator dot color |
| `autoplay` | `boolean` | No | `false` | Whether to enable autoplay |
| `current` | `number` | No | `0` | Index of the current slide |
| `interval` | `number` | No | `5000` | Autoplay interval |
| `duration` | `number` | No | `500` | Slide animation duration |
| `circular` | `boolean` | No | `false` | Whether to enable circular sliding |
| `vertical` | `boolean` | No | `false` | Whether the sliding direction is vertical |
| `dataSource` | `I[]` | No | - | List data used with renderItem for rendering; the generic I infers the data type of each item. You can also omit dataSource and render directly with SwiperItem as children. |
| `renderItem` | `(item: I, index: number) => any` | No | - | Render each list item; the item type is inferred from the generic I of dataSource. |
| `onChange` | `(event: SwiperComponentChangeEvent) => void` | No | - | Triggered when current changes |
| `onAfterChange` | `(event: SwiperComponentAfterChangeEvent) => void` | No | - | Triggered when the animation ends |

### Referenced Types

##### `interface` SwiperComponentChangeEvent

| Property | Type | Description |
| --- | --- | --- |
| `type` | `"change"` | Event type |
| `current` | `number` | Current slide index |
| `source` | `"" \| "autoplay" \| "touch"` | Trigger source |
| `detail` | `SwiperChangeDetail` | Event data |

##### `interface` SwiperComponentAfterChangeEvent

| Property | Type | Description |
| --- | --- | --- |
| `type` | `"afterChange"` | Event type |
| `current` | `number` | Current slide index |
| `source` | `"" \| "autoplay" \| "touch"` | Trigger source |
| `detail` | `SwiperChangeDetail` | Event data |

##### `interface` SwiperChangeDetail

| Property | Type | Description |
| --- | --- | --- |
| `current` | `number` | Current slide index |
| `currentItemId` | `string` | Current slide ID |
| `source` | `"" \| "autoplay" \| "touch"` | Trigger source |

##### `interface` BaseEvent

| Property | Type | Description |
| --- | --- | --- |
| `type` | `string` | Event type |
| `timeStamp` | `number` | Time in milliseconds since the page opened |
| `target` | `Target` | Source component of the event |
| `currentTarget` | `Target` | Collection of property values for the current component |
| `mark` | `any` | Event mark data |

##### `interface` Target

| Property | Type | Description |
| --- | --- | --- |
| `id` | `string` | id of the event source component |
| `dataset` | `Record<string, unknown>` | Collection of custom attributes from the `dataset` on the event source component |


### Examples

#### Basic usage

```tsx
import React, { useState } from 'react';
import { Swiper, SwiperItem, View, Button, Text } from '@ray-js/ray';

export default function BasicSwiper() {
  const [current, setCurrent] = useState(0);
  const colors = ['#1890ff', '#52c41a', '#faad14'];

  return (
    <View>
      <Swiper
        style={{ width: '702rpx', height: '200rpx' }}
        dots
        current={current}
        onChange={(e) => setCurrent(e.current)}
      >
        {colors.map((color, index) => (
          <SwiperItem key={index}>
            <View
              style={{
                width: '100%',
                height: '100%',
                backgroundColor: color,
                display: 'flex',
                alignItems: 'center',
                justifyContent: 'center',
              }}
            >
              <Text style={{ color: '#fff' }}>Page {index + 1}</Text>
            </View>
          </SwiperItem>
        ))}
      </Swiper>
      <Button
        style={{ marginTop: '20rpx' }}
        onClick={() => setCurrent((current + 1) % 3)}
      >
        Switch to page {(current + 1) % 3 + 1}
      </Button>
    </View>
  );
}
```

#### Auto-play and dataSource

```tsx
import React, { useState } from 'react';
import { Swiper, View, Text } from '@ray-js/ray';

export default function AutoplaySwiper() {
  const [current, setCurrent] = useState(0);
  const dataSource = [
    { id: '1', color: '#1890ff', label: 'Slide 1' },
    { id: '2', color: '#52c41a', label: 'Slide 2' },
    { id: '3', color: '#faad14', label: 'Slide 3' },
  ];

  return (
    <Swiper
      style={{ width: '702rpx', height: '200rpx' }}
      autoplay
      interval={2500}
      circular
      dots
      current={current}
      dataSource={dataSource}
      renderItem={(item) => (
        <View
          style={{
            width: '100%',
            height: '100%',
            backgroundColor: item.color,
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center',
          }}
        >
          <Text style={{ color: '#fff', fontSize: '32rpx' }}>{item.label}</Text>
        </View>
      )}
      onChange={(e) => setCurrent(e.current)}
    />
  );
}
```

#### Vertical carousel and indicator dot color

```tsx
import React, { useState } from 'react';
import { Swiper, View, Text } from '@ray-js/ray';

export default function VerticalSwiper() {
  const [current, setCurrent] = useState(0);
  const dataSource = [
    { id: '1', color: '#722ed1', label: 'Vertical 1' },
    { id: '2', color: '#eb2f96', label: 'Vertical 2' },
    { id: '3', color: '#13c2c2', label: 'Vertical 3' },
  ];

  return (
    <Swiper
      style={{ width: '702rpx', height: '300rpx' }}
      vertical
      dots
      dotColor="rgba(255,255,255,0.4)"
      dotActiveColor="#fff"
      duration={400}
      current={current}
      dataSource={dataSource}
      renderItem={(item) => (
        <View
          style={{
            width: '100%',
            height: '100%',
            backgroundColor: item.color,
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center',
          }}
        >
          <Text style={{ color: '#fff', fontSize: '32rpx' }}>{item.label}</Text>
        </View>
      )}
      onChange={(e) => setCurrent(e.current)}
      onAfterChange={(e) => console.log('Animation ended:', e.current)}
    />
  );
}
```