Swiper Vue.js Components

Swiper Vue.js components are compatible only with new Vue.js version 3

Installation

Swiper Vue.js plugin is available only via NPM as a part of the main Swiper library:

npm i swiper

Usage

swiper/vue exports 2 components: Swiper and SwiperSlide:

<template>
  <swiper
    :slides-per-view="3"
    :space-between="50"
    @swiper="onSwiper"
    @slideChange="onSlideChange"
  >
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
    ...
  </swiper>
</template>
<script>
  // Import Swiper Vue.js components
  import { Swiper, SwiperSlide } from 'swiper/vue';

  // Import Swiper styles
  export default {
    components: {
      Swiper,
      SwiperSlide,
    },
    methods: {
      onSwiper(swiper) {
        console.log(swiper)
      },
      onSlideChange() {
        console.log('slide change')
      },
    },
  };
</script>

By default Swiper Vue.js uses core version of Swiper (without any additional components). If you want to use Navigation, Pagination and other components, you have to install them first.

Here is the list of additional modules imports:

<template>
  <swiper
    :slides-per-view="3"
    :space-between="50"
    navigation
    :pagination="{ clickable: true }"
    :scrollbar="{ draggable: true }"
    @swiper="onSwiper"
    @slideChange="onSlideChange"
  >
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
    ...
  </swiper>
</template>
<script>
  // import Swiper core and required components
  import SwiperCore, { Navigation, Pagination, Scrollbar, A11y } from 'swiper';

  // Import Swiper Vue.js components
  import { Swiper, SwiperSlide } from 'swiper/vue';

  // Import Swiper styles
  import 'swiper/swiper.scss';
  import 'swiper/components/navigation/navigation.scss';
  import 'swiper/components/pagination/pagination.scss';
  import 'swiper/components/scrollbar/scrollbar.scss';

  // install Swiper components
  SwiperCore.use([Navigation, Pagination, Scrollbar, A11y]);

  // Import Swiper styles
  export default {
    components: {
      Swiper,
      SwiperSlide,
    },
    methods: {
      onSwiper(swiper) {
        console.log(swiper)
      },
      onSlideChange() {
        console.log('slide change')
      },
    },
  };
</script>

Note, Swiper Vue.js component will create required elements for Navigation, Pagination and Scrollbar if you pass these params without specifying its elements (e.g. without navigation.nextEl, pagination.el, etc.)

Styles

Swiper package contains different sets of CSS, Less and SCSS styles:

CSS Styles

CSS styles available only for bundle version:

Less Styles

Less styles are separate styles for core version and components:

SCSS Styles

SCSS styles are also separate styles for core version and components:

Swiper props

Swiper Vue.js component receive all Swiper parameters as component props, plus some extra props:

PropTypeDefaultDescription
tagstring'div'Main Swiper container HTML element tag
wrapperTagstring'div'Swiper wrapper HTML element tag

Swiper events

Swiper component supports all Swiper events, including additional swiper event that returns swiper instance as soon as posible. For example:

<swiper
  @swiper="..."
  @slideChange="..."
  @reachEnd="..."
  ...
>

SwiperSlide props

PropTypeDefaultDescription
tagstring'div'Swiper Slide HTML element tag
zoombooleanfalseEnables additional wrapper required for zoom mode
virtualIndexnumberActual swiper slide index. Required to be set for virtual slides

SwiperSlide slot props

SwiperSlide component has the following slot props:

For example:

<swiper>
  <swiper-slide v-slot="{ isActive }">
    <div>Current slide is {{ isActive ? 'active' : 'not active' }}</div>
  </swiper-slide>
</swiper>

Slots

Swiper Vue.js component uses "slots" for content distribution. There are 4 slots available

For example:

<swiper>
  <swiper-slide>Slide 1</swiper-slide>
  <swiper-slide>Slide 2</swiper-slide>
  <span slot="container-start">Container Start</span>
  <span slot="container-end">Container End</span>
  <span slot="wrapper-start">Wrapper Start</span>
  <span slot="wrapper-end">Wrapper End</span>
</swiper>

Will be rendered as:

<div class="swiper-container">
  <span slot="container-start">Container Start</span>
  <div class="swiper-wrapper">
    <span slot="wrapper-start">Wrapper Start</span>
    <div class="swiper-slide">Slide 1</div>
    <div class="swiper-slide">Slide 2</div>
    <span slot="wrapper-end">Wrapper End</span>
  </div>
  <span slot="container-end">Container End</span>
</div>

Virtual Slides

Virtual Slides rendering here is fully handled by Vue.js and not required anything except setting :virtual="true" property and setting virtualIndex on slides:

<template>
  <swiper
    :slides-per-view="3"
    :space-between="50"
    virtual
  >
    <swiper-slide
      v-for="(slideContent, index) in slides"
      :key="slide"
      :virtualIndex="index"
    >{slideContent}</swiper-slide>
  </swiper>
</template>
<script>
  import SwiperCore, { Virtual } from 'swiper';
  import { Swiper, SwiperSlide } from 'swiper/vue';

  // install Virtual module
  SwiperCore.use([Virtual]);

  export default {
    components: {
      Swiper,
      SwiperSlide,
    },

    data() {
      // Create array with 1000 slides
      const slides = Array.from({ length: 1000 }).map((el, index) => `Slide ${index + 1}`);
      return {
        slides,
      };
    },
  };
</script>

Controller

Controller requires to pass one Swiper instance to another:

<template>
  <!-- Main Swiper -> pass controlled swiper instance -->
  <swiper :controller="{ control: controlledSwiper }" ...>
    ...
  </swiper>

  <!-- Controlled Swiper -> store swiper instance -->
  <swiper @swiper="setControlledSwiper" ...>
    ...
  </swiper>
</template>
<script>
  import SwiperCore, { Controller } from 'swiper';
  import { Swiper, SwiperSlide } from 'swiper/vue';

  // install Swiper's Controller component
  SwiperCore.use([Controller]);

  export default {
    components: {
      Swiper,
      SwiperSlide,
    },
    data() {
      return {
        controlledSwiper: null,
      };
    },
    methods: {
      setControlledSwiper(swiper) {
        this.controlledSwiper = swiper;
      },
    }
  };
</script>

For two-way control (when both Swipers control each other) it should be like this:

<template>
  <swiper @swiper="setFirstSwiper" :controller="{ control: secondSwiper }" ...>
    ...
  </swiper>
  <swiper @swiper="setSecondSwiper" :controller="{ control: firstSwiper }" ...>
    ...
  </swiper>
</template>
<script>
  import SwiperCore, { Controller } from 'swiper';
  import { Swiper, SwiperSlide } from 'swiper/vue';

  // install Swiper's Controller component
  SwiperCore.use([Controller]);

  export default {
    components: {
      Swiper,
      SwiperSlide,
    },
    data() {
      return {
        firstSwiper: null,
        secondSwiper: null,
      };
    },
    methods: {
      setFirstSwiper(swiper) {
        this.firstSwiper = swiper;
      },
      setSecondSwiper(swiper) {
        this.secondSwiper = swiper;
      },
    }
  };
</script>

Thumbs

Same as with controller we need to store thumbs instance and pass it to main gallery:

<template>
  <!-- Main Swiper -> pass thumbs swiper instance -->
  <swiper
    :thumbs="{ swiper: thumbsSwiper }"
    ...
  >
    ...
  </swiper>

  <!-- Thumbs Swiper -> store swiper instance -->
  <!-- It is also required to set watchSlidesVisibility and watchSlidesProgress props -->
  <swiper
    @swiper="setThumbsSwiper"
    watch-slides-visibility
    watch-slides-progress
    ...
  >
    ...
  </swiper>
</template>
<script>
  import SwiperCore, { Thumbs } from 'swiper';
  import { Swiper, SwiperSlide } from 'swiper/vue';

  // install Swiper's Thumbs component
  SwiperCore.use([Thumbs]);

  export default {
    components: {
      Swiper,
      SwiperSlide,
    },
    data() {
      return {
        thumbsSwiper: null,
      };
    },
    methods: {
      setThumbsSwiper(swiper) {
        this.thumbsSwiper = swiper;
      },
    }
  };
</script>

Effects

The following effects are available:

To use effects you have to import and install them first (as all other modules) (Fade example):

import SwiperCore, {EffectFade} from 'swiper';

SwiperCore.use([EffectFade]);

You can find running effect demos here.

Full Fade Effect Example

<template>
  <swiper effect="fade">
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
    <swiper-slide>Slide 3</swiper-slide>
    ...
  </swiper>
</template>
<script>
  import SwiperCore, { EffectFade } from 'swiper';
  import { Swiper, SwiperSlide } from 'swiper/vue';

  import 'swiper/swiper.scss';
  import 'swiper/components/effect-fade/effect-fade.scss';

  SwiperCore.use([EffectFade]);

  export default {
    components: {
      Swiper,
      SwiperSlide,
    },
  };
</script>