Swiper

17:06

Description

A carousel that takes a list array and loops with autoplay, supporting four indicators (rect / dot / round / number) via mode, an indicator position (indicatorPos), a 3D effect (effect3d), a bottom title overlay (title), plus corner radius, height and switch interval. Each list item can be either an image URL string or an object with an image field and a title (the image field name is set by name, default image).

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported (swiper is a native component and the item/indicator transition is disabled, so switching and the 3D scale are instant with no transition)

Examples

Basic Usage

Autoplay and loop by default, with a rounded indicator at the bottom.

View source

<template>
    <ux-swiper :list="list" />
</template>

<script setup lang="uts">
type SwiperItem = {
    image: string;
    title?: string;
};

const list: SwiperItem[] = [
    { image: 'https://picsum.photos/id/1015/600/300' },
    { image: 'https://picsum.photos/id/1016/600/300' },
    { image: 'https://picsum.photos/id/1018/600/300' }
];
</script>

Indicator Mode

Switch between rect/dot/round/number indicators via the mode prop.

View source

<template>
    <ux-swiper :list="list" :mode="mode" />
    <view class="btn-wrap">
        <ux-button v-for="(item, index) in modeList" :key="index" :type="mode === item.value ? 'primary' : 'default'" custom-class="btn-item" size="small" @click="mode = item.value">{{ item.label }}</ux-button>
    </view>
</template>

<script setup lang="uts">
import type { SwiperMode } from '@/uni_modules/uview-pro-x';

type SwiperItem = {
    image: string;
    title?: string;
};

type ModeItem = {
    value: SwiperMode;
    label: string;
};

const list: SwiperItem[] = [
    { image: 'https://picsum.photos/id/1015/600/300' },
    { image: 'https://picsum.photos/id/1016/600/300' },
    { image: 'https://picsum.photos/id/1018/600/300' }
];

const mode = ref<SwiperMode>('round');

const modeList: ModeItem[] = [
    { value: 'rect', label: '矩形' },
    { value: 'dot', label: '圆点' },
    { value: 'round', label: '圆条' },
    { value: 'number', label: '数字' }
];
</script>

<style scoped>
.btn-wrap {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    align-items: center;
    margin-top: 12px;
}
.btn-item {
    margin-right: 12px;
    margin-bottom: 12px;
}
</style>

3D Effect

When effect3d=true, inactive items scale down with side margins for a 3D feel.

View source

<template>
    <ux-swiper :list="list" :effect3d="true" />
</template>

<script setup lang="uts">
type SwiperItem = {
    image: string;
    title?: string;
};

const list: SwiperItem[] = [
    { image: 'https://picsum.photos/id/1015/600/300' },
    { image: 'https://picsum.photos/id/1016/600/300' },
    { image: 'https://picsum.photos/id/1018/600/300' }
];
</script>

Title Display

When title=true, the title field in the list data is overlaid at the bottom.

View source

<template>
    <ux-swiper :list="list" :title="true" height="100" />
</template>

<script setup lang="uts">
type SwiperItem = {
    image: string;
    title?: string;
};

const list: SwiperItem[] = [
    { image: 'https://picsum.photos/id/1015/600/300', title: '风景一' },
    { image: 'https://picsum.photos/id/1016/600/300', title: '风景二' },
    { image: 'https://picsum.photos/id/1018/600/300', title: '风景三' }
];
</script>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	string | UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
list	Carousel data list (array of items)	any[]	-	-
title	Whether to show the title	boolean	false	-
borderRadius	Corner radius, in px	string | number	4	-
interval	Auto-switch interval, in ms	string | number	3000	-
mode	Indicator type: round/dot/rect/number/none	SwiperMode	'round'	-
height	Carousel height, in px	string | number	125	-
indicatorPos	Indicator position	SwiperIndicatorPosition	'bottomCenter'	-
effect3d	Whether to enable the 3D effect	boolean	false	-
effect3dPreviousMargin	Margin of the previous item in 3D mode, in px	string | number	25	-
autoplay	Whether to autoplay	boolean	true	-
duration	Switch animation duration, in ms	string | number	500	-
circular	Whether to loop	boolean	true	-
imgMode	Image crop mode	ImgMode	'aspectFill'	-
name	Image field name of each carousel item object	string	'image'	-
bgColor	Carousel background color	string	''	-
current	Index of the currently active item	string | number	0	-
titleStyle	Title style object	UTSJSONObject	-	-

Events

Event	Description	Params	Version
click	Fired when a carousel item is clicked; param: index (index of the clicked item)	index: number	-
change	Fired when the carousel switches; param: current (index of the active item)	current: number	-

Slots

ux-swiper has no slots.

Notes

1. mode only implements rect / dot / round / number; with mode="none" no indicator is rendered.
2. effect3d only reveals the neighbouring items when true (through previous-margin / next-margin, with the gap controlled by effect3dPreviousMargin, default 25px); when not in 3D the margins are 0, and inactive items get scaleY(0.9) plus 10px left/right margins.
3. When a list item is an object, the image field name is set by name (default image) and the title comes from the object's title field, which is shown only when title=true.
4. When the list length changes, the internal active index resets to 0; current is only used for initial positioning and external control, and is not written back after the user swipes manually — listen to change if you need to keep it in sync.
5. Although the click event is declared in the API, the current source template does not bind a click handler on carousel items, so a real click does not emit it; wrap the item in a clickable element yourself if you need click handling.
6. On WeChat Mini Program transition is disabled (to avoid jank alongside native components), so switching and the 3D scale have no transition.
7. The title is overlaid at the bottom of the image as white text on a translucent black background; when mode="number" and the indicator is at the bottom, the title reserves 30px of bottom padding so the indicator does not cover it.
8. interval defaults to 3000ms, duration to 500ms and imgMode to aspectFill.