Migrating From ion-slides to Swiper.js

Looking forion-slides?

ion-slides was deprecated in v6.0.0 and removed in v7.0.0. We recommend using the Swiper.js library directly. The migration process is detailed below.

We recommend Swiper.js if you need a modern touch slider component. This guide will go over how to get Swiper for Vue set up in your Ionic Framework application. It will also go over any migration information you may need to move fromion-slides to the official Swiper Vue integration.

note

Swiper's Vue component is set to be removed in a future release of Swiper, withSwiper Element as the replacement. However, this guide shows how to migrate to the Vue component because it provides the most stable experience at the time of writing.

Using Swiper's Vue component isnot required to use Swiper.js with Ionic Framework.

Getting Started

First, update to the latest version of Ionic:

npm install @ionic/vue@latest @ionic/vue-router@latest

We recommend upgrading to Vue CLI 5 for better compatibility with Swiper:

vue upgrade --next

Once that is done, install the Swiper dependency in your project:

npm install swiper@latest

Swiping with Style

Next, we need to import the base Swiper styles. We are also going to import the styles that Ionic provides which will let us customize the Swiper styles using the same CSS Variables that we used withion-slides.

We recommend importing the styles in the component in which Swiper is being used. This ensures that the styles are only loaded when needed:

<scriptsetuplang="ts">
import'swiper/css';
import'@ionic/vue/css/ionic-swiper.css';
</script>

note

Importing@ionic/vue/css/ionic-swiper.css isnot required to use Swiper.js with Ionic. This files is used for backward-compatibility with theion-slides component and can be safely omitted if you prefer not to use the CSS Variables provided in the stylesheet.

Updating Selectors

Previously, we were able to targetion-slides andion-slide to apply any custom styling. The contents of those style blocks remain the same, but we need to update the selectors. Below is a list of selector changes when going fromion-slides to Swiper Vue:

ion-slides Selector	Swiper Selector
`ion-slides`	`.swiper`
`ion-slide`	`.swiper-slide`

Pre-processors (optional)

For developers using SCSS or Less styles, Swiper also provides imports for those files.

For Less styles, replacecss withless in the Swiper import path:

import'swiper/less';
import'@ionic/vue/css/ionic-swiper.css';

For SCSS styles replacecss withscss in the Swiper import path:

import'swiper/scss';
import'@ionic/vue/css/ionic-swiper.css';

Using Components

Swiper exports two components:Swiper andSwiperSlide. TheSwiper component is the equivalent ofIonSlides, andSwiperSlide is the equivalent ofIonSlide.

These components are imported fromswiper/vue and provided to your Vue component:

<template>
<ion-page>
<ion-content>
<swiper>
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper>
</ion-content>
</ion-page>
</template>

<scriptsetuplang="ts">
import{Swiper,SwiperSlide}from'swiper/vue';
import{IonContent,IonPage}from'@ionic/vue';

import'swiper/css';
import'@ionic/vue/css/ionic-swiper.css';
</script>

Using Modules

By default, Swiper for Vue does not import any additional modules. To use modules such as Navigation or Pagination, you need to import them first.

ion-slides automatically included the Pagination, Scrollbar, Autoplay, Keyboard, and Zoom modules. This part of the guide will show you how to install these modules.

To begin, we need to import the modules and their corresponding CSS files from theswiper package:

<template>
<ion-page>
<ion-content>
<swiper>
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper>
</ion-content>
</ion-page>
</template>
<scriptsetuplang="ts">
import{Autoplay,Keyboard,Pagination,Scrollbar,Zoom}from'swiper/modules';
import{Swiper,SwiperSlide}from'swiper/vue';
import{IonContent,IonPage}from'@ionic/vue';

import'swiper/css';
import'swiper/css/autoplay';
import'swiper/css/keyboard';
import'swiper/css/pagination';
import'swiper/css/scrollbar';
import'swiper/css/zoom';
import'@ionic/vue/css/ionic-swiper.css';
</script>

From here, we need to provide these modules to Swiper by using themodules property on theswiper component:

<template>
<ion-page>
<ion-content>
<swiper:modules="modules">
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper>
</ion-content>
</ion-page>
</template>
<script>
import{Autoplay,Keyboard,Pagination,Scrollbar,Zoom}from'swiper/modules';
import{Swiper,SwiperSlide}from'swiper/vue';
import{IonContent,IonPage}from'@ionic/vue';

import'swiper/css';
import'swiper/css/autoplay';
import'swiper/css/keyboard';
import'swiper/css/pagination';
import'swiper/css/scrollbar';
import'swiper/css/zoom';
import'@ionic/vue/css/ionic-swiper.css';

const modules=[Autoplay,Keyboard,Pagination,Scrollbar,Zoom];
</script>

Finally, we can turn these features on by using the appropriate properties:

<template>
<ion-page>
<ion-content>
<swiper:modules="modules":autoplay="true":keyboard="true":pagination="true":scrollbar="true":zoom="true">
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper>
</ion-content>
</ion-page>
</template>
<script>
import{Autoplay,Keyboard,Pagination,Scrollbar,Zoom}from'swiper/modules';
import{Swiper,SwiperSlide}from'swiper/vue';
import{IonContent,IonPage}from'@ionic/vue';

import'swiper/css';
import'swiper/css/autoplay';
import'swiper/css/keyboard';
import'swiper/css/pagination';
import'swiper/css/scrollbar';
import'swiper/css/zoom';
import'@ionic/vue/css/ionic-swiper.css';

const modules=[Autoplay,Keyboard,Pagination,Scrollbar,Zoom];
</script>

note

See https://swiperjs.com/vue#usage for a full list of modules.

The IonicSlides Module

Withion-slides, Ionic automatically customized dozens of Swiper properties. This resulted in an experience that felt smooth when swiping on mobile devices. We recommend using theIonicSlides module to ensure that these properties are also set when using Swiper directly. However, using this module isnot required to use Swiper.js in Ionic.

It is recommended to review theproperties set byIonicSlides and determine which ones you would like to customize.

We can install theIonicSlides module by importing it from@ionic/vue and passing it in as the last item in themodules array:

<template>
<ion-page>
<ion-content>
<swiper:modules="modules":autoplay="true":keyboard="true":pagination="true":scrollbar="true":zoom="true">
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper>
</ion-content>
</ion-page>
</template>
<scriptsetuplang="ts">
import{Autoplay,Keyboard,Pagination,Scrollbar,Zoom}from'swiper/modules';
import{Swiper,SwiperSlide}from'swiper/vue';
import{IonContent,IonPage,IonicSlides}from'@ionic/vue';

import'swiper/css';
import'swiper/css/autoplay';
import'swiper/css/keyboard';
import'swiper/css/pagination';
import'swiper/css/scrollbar';
import'swiper/css/zoom';
import'@ionic/vue/css/ionic-swiper.css';

const modules=[Autoplay,Keyboard,Pagination,Scrollbar,Zoom,IonicSlides];
</script>

note

TheIonicSlides module must be the last module in the array. This will let it automatically customize the settings of modules such as Pagination, Scrollbar, Zoom, and more.

Properties

Swiper options are provided as props directly on the<swiper> component rather than via theoptions object inion-slides.

Let's say in an app withion-slides we had theslidesPerView andloop options set:

<template>
<ion-slides:options="{ slidesPerView: 3, loop: true }">
<ion-slide>Slide 1</ion-slide>
<ion-slide>Slide 2</ion-slide>
<ion-slide>Slide 3</ion-slide>
</ion-slides>
</template>

To migrate, we would move these options out of theoptions object and onto the<swiper> component directly as properties:

<template>
<swiper:slides-per-view="3":loop="true">
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper>
</template>

Below is a full list of property changes when going fromion-slides to Swiper Vue:

Name	Notes
options	Set each option as a property directly on the`<swiper>` component.
mode	For different styles based upon the mode, you can target the slides with`.ios .swiper` or`.md .swiper` in your CSS.
pager	Use the`pagination` property instead. Requires installation of the Pagination module.
scrollbar	You can continue to use the`scrollbar` property, just be sure to install the Scrollbar module first.

note

All properties available in Swiper Vue can be found at https://swiperjs.com/vue#swiper-props.

Events

Since theSwiper component is not provided by Ionic Framework, event names will not have anionSlide prefix to them.

Let's say in an app withion-slides we used theionSlideDidChange event:

<template>
<ion-slides@ionSlideDidChange="onSlideChange">
<ion-slide>Slide 1</ion-slide>
<ion-slide>Slide 2</ion-slide>
<ion-slide>Slide 3</ion-slide>
</ion-slides>
</template>

To migrate, we would change the name of the event toslideChange:

<template>
<swiper@slideChange="onSlideChange">
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper>
</template>

Below is a full list of event name changes when going fromion-slides to Swiper Vue:

ion-slides Event	Swiper Event
`ionSlideWillChange`	`slideChangeTransitionStart`
`ionSlideDidChange`	`slideChangeTransitionEnd`
`ionSlideDoubleTap`	`doubleTap`
`ionSlideDrag`	`sliderMove`
`ionSlideNextStart`	`slideNextTransitionStart`
`ionSlideNextEnd`	`slideNextTransitionEnd`
`ionSlidePrevStart`	`slidePrevTransitionStart`
`ionSlidePrevEnd`	`slidePrevTransitionEnd`
`ionSlideReachStart`	`reachBeginning`
`ionSlideReachEnd`	`reachEnd`
`ionSlideTap`	`tap`
`ionSlideTouchStart`	`touchStart`
`ionSlideTouchEnd`	`touchEnd`
`ionSlideTransitionStart`	`transitionStart`
`ionSlideTransitionEnd`	`transitionEnd`
`ionSlidesDidLoad`	`init`

note

All events available in Swiper Vue can be found at https://swiperjs.com/vue#swiper-events.

Methods

Most methods have been removed in favor of accessing the<swiper> props directly. Additionally, you no longer need to access$el first when calling methods.

Accessing these properties can be tricky as you want to access the properties on the Swiper instance itself, not your Vue component. To do this, we recommend getting a reference to the Swiper instance via the@swiper event handler:

<template>
<swiper@swiper="setSwiperInstance"> ...</swiper>
</template>

<scriptsetuplang="ts">
import{ ref}from'vue';

const slides=ref();
constsetSwiperInstance=(swiper: any)=>{
  slides.value= swiper;
};
</script>

From here, if you wanted to access a property on the Swiper instance you would accessslides.value. For example, if you wanted to check theisBeginning property, you could do:slides.value.isBeginning. Make sureslides.value is defined first though!

Below is a full list of method changes when going fromion-slides to Swiper Vue:

ion-slides Method	Notes
`getActiveIndex()`	Use the`activeIndex` property instead.
`getPreviousIndex()`	Use the`previousIndex` property instead.
`getSwiper()`	Get a reference to the Swiper instance using`@swiper`. See example above.
`isBeginning()`	Use the`isBeginning` property instead.
`isEnd()`	Use the`isEnd` property instead.
`length()`	Use the`slides` property instead. (i.e swiperRef.slides.length)
`lockSwipeToNext()`	Use the`allowSlideNext` property instead.
`lockSwipeToPrev()`	Use the`allowSlidePrev` property instead.
`lockSwipes()`	Use the`allowSlideNext`,`allowSlidePrev`, and`allowTouchMove` properties instead.
`startAutoplay()`	Use the`autoplay` property instead.
`stopAutoplay()`	Use the`autoplay` property instead.

Effects

If you are using effects such as Cube or Fade, you can install them just like we did with the other modules. In this example, we will use the fade effect. To start, we will importEffectFade fromswiper and provide it in themodules array:

<template>
<ion-page>
<ion-content>
<swiper:modules="modules">
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper>
</ion-content>
</ion-page>
</template>
<script>
import{EffectFade}from'swiper/modules';
import{Swiper,SwiperSlide}from'swiper/vue';
import{IonContent,IonPage,IonicSlides}from'@ionic/vue';

import'swiper/css';
import'@ionic/vue/css/ionic-swiper.css';

const modules=[EffectFade,IonicSlides];
</script>

Next, we need to import the stylesheet associated with the effect:

<template>
<ion-page>
<ion-content>
<swiper:modules="modules">
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper>
</ion-content>
</ion-page>
</template>
<script>
import{EffectFade}from'swiper/modules';
import{Swiper,SwiperSlide}from'swiper/vue';
import{IonContent,IonPage,IonicSlides}from'@ionic/vue';

import'swiper/css';
import'swiper/css/effect-fade';
import'@ionic/vue/css/ionic-swiper.css';

const modules=[EffectFade,IonicSlides];
</script>

After that, we can activate it by setting theeffect property onswiper to"fade":

<template>
<ion-page>
<ion-content>
<swiper:modules="modules"effect="fade">
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper>
</ion-content>
</ion-page>
</template>
<script>
import{EffectFade}from'swiper/modules';
import{Swiper,SwiperSlide}from'swiper/vue';
import{IonContent,IonPage,IonicSlides}from'@ionic/vue';

import'swiper/css';
import'swiper/css/effect-fade';
import'@ionic/vue/css/ionic-swiper.css';

const modules=[EffectFade,IonicSlides];
</script>

note

For more information on effects in Swiper, please see https://swiperjs.com/vue#effects.

Wrap Up

Now that you have Swiper installed, there is a whole set of new Swiper features for you to enjoy. We recommend starting with theSwiper Vue Introduction and then referencingthe Swiper API docs.

FAQ

Where can I find an example of this migration?

You can find a sample app withion-slides and the equivalent Swiper usage athttps://github.com/ionic-team/slides-migration-samples.

Where can I get help with this migration?

If you are running into issues with the migration, please create a post on theIonic Forum.

Where do I file bug reports?

Before opening an issue, please consider creating a post on theSwiper Discussion Board or theIonic Forum to see if your issue can be resolved by the community.

If you are running into problems with the Swiper library, new bugs should be filed on the Swiper repo:https://github.com/nolimits4web/swiper/issues

If you are running into problems with theIonicSlides module, new bugs should be filed on the Ionic Framework repo:https://github.com/ionic-team/ionic-framework/issues

Edit this page

Getting Started

Swiping with Style

Updating Selectors

Pre-processors (optional)

Using Components

Using Modules

The IonicSlides Module

Properties

Events

Methods

Effects

Wrap Up

FAQ

Where can I find an example of this migration?

Where can I get help with this migration?

Where do I file bug reports?

Movatterモバイル変換

Migrating From ion-slides to Swiper.js

Contents

Movatterモバイル変換

Getting Started​

Swiping with Style​

Updating Selectors​

Pre-processors (optional)​

Using Components​

Using Modules​

The IonicSlides Module​

Properties​

Events​

Methods​

Effects​

Wrap Up​

FAQ​

Where can I find an example of this migration?​

Where can I get help with this migration?​

Where do I file bug reports?​

Contents

Getting Started

Swiping with Style

Updating Selectors

Pre-processors (optional)

Using Components

Using Modules

The IonicSlides Module

Properties

Events

Methods

Effects

Wrap Up

FAQ

Where can I find an example of this migration?

Where can I get help with this migration?

Where do I file bug reports?