vue-awesome-swiper

Swiper component for Vue.

Old versions:

• Swiper 4: v3.1.3
• Swiper 3: v2.6.7

Example

• Online examples
• CDN example
• SSR example code
• TypeScript & composition-api example code

---

Install

1npm install swiper vue-awesome-swiper --save
2
3# or
4yarn add swiper vue-awesome-swiper
5
6# Swiper5 is recommended
7yarn add swiper@5.x vue-awesome-swiper

Global Registration

1import Vue from 'vue'
2import VueAwesomeSwiper from 'vue-awesome-swiper'
3
4// import style (>= Swiper 6.x)
5import 'swiper/swiper-bundle.css'
6
7// import style (<= Swiper 5.x)
8import 'swiper/css/swiper.css'
9
10Vue.use(VueAwesomeSwiper, /* { default options with global component } */)

Local Registration

1import { Swiper, SwiperSlide, directive } from 'vue-awesome-swiper'
2
3// import style (>= Swiper 6.x)
4import 'swiper/swiper-bundle.css'
5
6// import style (<= Swiper 5.x)
7import 'swiper/css/swiper.css'
8
9export default {
10  components: {
11    Swiper,
12    SwiperSlide
13  },
14  directives: {
15    swiper: directive
16  }
17}

CDN

1<link rel="stylesheet" href="path/to/swiper.css"/>
2<script type="text/javascript" src="path/to/swiper.js"></script>
3<script type="text/javascript" src="path/to/vue.min.js"></script>
4<script type="text/javascript" src="path/to/dist/vue-awesome-swiper.js"></script>
5<script type="text/javascript">
6  Vue.use(window.VueAwesomeSwiper)
7</script>

---

Difference with usage

Directive and the only difference in the use of the Component:

• component find Swiper instance by ref attribute.
• directive find Swiper instance by directive arg.

Other configurations, events are the same.

The effect of the two ways and the difference in the applicable environment is here.

Component

1<template>
2  <swiper ref="mySwiper" :options="swiperOptions">
3    <swiper-slide>Slide 1</swiper-slide>
4    <swiper-slide>Slide 2</swiper-slide>
5    <swiper-slide>Slide 3</swiper-slide>
6    <swiper-slide>Slide 4</swiper-slide>
7    <swiper-slide>Slide 5</swiper-slide>
8    <div class="swiper-pagination" slot="pagination"></div>
9  </swiper>
10</template>
11
12<script>
13  export default {
14    name: 'carrousel',
15    data() {
16      return {
17        swiperOptions: {
18          pagination: {
19            el: '.swiper-pagination'
20          },
21          // Some Swiper option/callback...
22        }
23      }
24    },
25    computed: {
26      swiper() {
27        return this.$refs.mySwiper.$swiper
28      }
29    },
30    mounted() {
31      console.log('Current Swiper instance object', this.swiper)
32      this.swiper.slideTo(3, 1000, false)
33    }
34  }
35</script>

Directive

1<template>
2  <div v-swiper:mySwiper="swiperOption">
3    <div class="swiper-wrapper">
4      <div class="swiper-slide" :key="banner" v-for="banner in banners">
5        <img :src="banner">
6      </div>
7    </div>
8    <div class="swiper-pagination"></div>
9  </div>
10</template>
11
12<script>
13  export default {
14    data () {
15      return {
16        banners: [ '/1.jpg', '/2.jpg', '/3.jpg' ],
17        swiperOption: {
18          pagination: {
19            el: '.swiper-pagination'
20          },
21          // ...
22        }
23      }
24    },
25    mounted() {
26      console.log('Current Swiper instance object', this.mySwiper)
27      this.mySwiper.slideTo(3, 1000, false)
28    }
29  }
30</script>

---

Swiper component API

1<!-- All events/props support camelCase or kebab-case. -->
2<swiper
3  :options="swiperOptionsObject"
4  :auto-update="true"
5  :auto-destroy="true"
6  :delete-instance-on-destroy="true"
7  :cleanup-styles-on-destroy="true"
8  @ready="handleSwiperReadied"
9  @click-slide="handleClickSlide"
10/>
11
12<!-- vue-awesome-swiper converts all Swiper events into component/directive events, e.g.: -->
13<swiper
14  @slide-change-transition-start="onSwiperSlideChangeTransitionStart"
15  @slideChangeTransitionStart="onSwiperSlideChangeTransitionStart"
16  @slideChangeTransitionEnd="..."
17  @transitionStart="..."
18  ...
19/>

1interface IProps {
2  // Auto update swiper when vue component `updated`
3  autoUpdate?: boolean // default: true
4  // Auto destroy swiper when vue component 'beforeDestroy'
5  autoDestroy?: boolean // default: true
6
7  // swiper.destroy's params
8  // swiper.destroy(deleteInstanceOnDestroy, cleanupStylesOnDestroy)
9  deleteInstanceOnDestroy?: boolean // default: true
10  cleanupStylesOnDestroy?: boolean // default: true
11}
12
13// `@ready` event will emit when the Swiper instance mounted
14function handleSwiperReadied(swiper: Swiper) {
15  console.log('Swiper was munted!', swiper)
16}
17
18// `@click-slide` event has special treatment for Swiper's loop mode, which is still available in loop mode
19function handleClickSlide(index: number, reallyIndex: number | null) {
20  console.log('Click slide!', index, reallyIndex)
21}

Swiper directive API

Based on the exact same as the component API.

In the directive mode, the Swiper instance will be mounted in the parent's component context use the default name$swiper. In order to implement multiple swipers in a context, the directive has an additional name called instanceName API, through this API, you can easily control the name of each swiper mount context.

1<div v-swiper="swiperOptionsObject" />
2<div v-swiper:secondSwiper="swiperOptionsObject" />
3<div v-swiper:[dynamicSwiperName]="swiperOptionsObject" />
4<div v-swiper="swiperOptionsObject" instance-name="fourthSwiper" />

1export dafault {
2  data() {
3    return {
4      dynamicSwiperName: 'thirdSwiper'
5    }
6  },
7  mounted() {
8    console.log('Swiper instances:', this.$swiper, this.secondSwiper, this.thirdSwiper, this.fourthSwiper)
9  }
10}

Swiper API

Swiper's API and configuration can be used.

• EN Swiper events
• EN Swiper documentation
• ZH Swiper documentation

---

Custom Build with Swiper

1import Vue from 'vue'
2// Swiper 5.x
3import { Swiper as SwiperClass, Pagination, Mousewheel, Autoplay } from 'swiper/js/swiper.esm'
4// Swiper 6.x
5import { Swiper as SwiperClass, Pagination, Mousewheel, Autoplay } from 'swiper/core'
6
7import getAwesomeSwiper from 'vue-awesome-swiper/dist/exporter'
8
9// Swiper modules
10SwiperClass.use([Pagination, Mousewheel, Autoplay])
11
12// -------------------------------------------------
13
14// Global use
15Vue.use(getAwesomeSwiper(SwiperClass))
16
17// -------------------------------------------------
18
19// Or local component
20const { Swiper, SwiperSlide } = getAwesomeSwiper(SwiperClass)
21export default {
22  components: {
23    Swiper,
24    SwiperSlide
25  }
26}

Custom Swiper plugin

1import SwiperClass from 'swiper'
2
3SwiperClass.use({
4  name: 'pluginName',
5  params: {
6    pluginSwitch: false,
7  },
8  on: {
9    init() {
10      if (!this.params.pluginSwitch) return
11      console.log('init')
12    },
13    // ...
14  }
15})
16
17// Your Swiper or App bussiness component...

---

Changelog

Detailed changes for each release are documented in the release notes.

License

MIT