We recommendSwiper.js if you need a modern touch slider component. Swiper 9 introducedSwiper Element as a replacement for its Angular component, so this guide will go over how to get Swiper Element set up in your Ionic Framework application. It will also go over any migration information you may need to move fromion-slides to Swiper Element.

Getting Started​

First, update to the latest version of Ionic:

npm install @ionic/angular@latest

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

npm install swiper@latest

Next, we need to add theCUSTOM_ELEMENTS_SCHEMA, which tells Angular that we will be using custom elements. This can be done in eitherapp.module.ts, or the module file for the component where you will be using Swiper.

import{CUSTOM_ELEMENTS_SCHEMA}from'@angular/core';

@NgModule({
  schemas:[...,CUSTOM_ELEMENTS_SCHEMA]
});
...

Finally, we need to call Swiper'sregister function to globally register Swiper's custom elements. This should only be done once, so place it inapp.component.ts.

import{ register}from'swiper/element/bundle';

register();

@Component({
...
})
...

From there, we just have to replaceion-slides elements withswiper-container andion-slide elements withswiper-slide. Note that these custom elements do not need to be imported, as callingregister tells Angular about them on its own.

<swiper-container>
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper-container>

Bundled vs. Core Versions​

By default, make sure you import theregister function fromswiper/element/bundle. This uses the bundled version of Swiper, which automatically includes all modules and stylesheets needed to run Swiper's various features.

If you would like to use the Core version instead, which does not include additional modules automatically, seehttps://swiperjs.com/element#core-version-and-modules. The rest of this migration guide will assume you are using the bundled version.

Swiping with Style​

To migrate over your CSS, first update your selectors to target the new custom elements instead:

If you were using the CSS custom properties found onion-slides, below is a list of corresponding properties used in Swiper.

For additional custom CSS, because Swiper Element uses Shadow DOM encapsulation, styles will need to be injected into the Shadow DOM scope. Seehttps://swiperjs.com/element#injecting-styles for instructions.

Additionalion-slides Styles​

Theion-slides component had additional styling that helped create a native look and feel. These styles arenot required to use Swiper.js with Ionic, but if you would like to maintain the look ofion-slides as closely as possible, add the following CSS to yourglobal.scss:

swiper-container{
--swiper-pagination-bullet-inactive-color:var(--ion-text-color-step-800,#cccccc);
--swiper-pagination-color:var(--ion-color-primary,#0054e9);
--swiper-pagination-progressbar-bg-color:rgba(var(--ion-text-color-rgb,0,0,0),0.25);
--swiper-scrollbar-bg-color:rgba(var(--ion-text-color-rgb,0,0,0),0.1);
--swiper-scrollbar-drag-bg-color:rgba(var(--ion-text-color-rgb,0,0,0),0.5);
}

swiper-slide{
display: flex;
position: relative;

flex-direction: column;
flex-shrink:0;
align-items: center;
justify-content: center;

width:100%;
height:100%;

font-size:18px;

text-align: center;
box-sizing: border-box;
}

swiper-slide img{
width: auto;
max-width:100%;
height: auto;
max-height:100%;
}

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 and passing it to themodules property ofswiper-container as an array:

// home.page.ts

import{ IonicSlides}from'@ionic/angular';

@Component({
...
})
exportclassHomePage{
  swiperModules=[IonicSlides];
}

// home.page.ts

import{ IonicSlides}from'@ionic/angular/standalone';

@Component({
...
})
exportclassHomePage{
  swiperModules=[IonicSlides];
}

<!-- home.page.html -->

<swiper-container[modules]="swiperModules"> ...</swiper-container>

Properties​

Swiper options should be provided as individual properties directly on the<swiper-container> component.

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

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

To set these options as properties directly on<swiper-container> we would do the following:

<swiper-container[slidesPerView]="3"[loop]="true">
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper-container>

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

Events​

Since theswiper-container component is not provided by Ionic Framework, event names will not have anionSlide prefix to them. Additionally, all event names should be lowercase instead of camelCase.

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

<ion-slides(ionSlideDidChange)="onSlideChange()">
<ion-slide>Slide 1</ion-slide>
<ion-slide>Slide 3</ion-slide>
<ion-slide>Slide 3</ion-slide>
</ion-slides>

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

<swiper-container(swiperslidechange)="onSlideChange()">
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper-container>

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

Methods​

Most methods have been removed in favor of directly accessing the properties of the Swiper instance. To access the Swiper instance, first get a reference to the<swiper-container> element (such as throughViewChild), then access itsswiper prop:

<!-- slides.component.html -->

<swiper-container#swiper>
<swiper-slide>Slide 1</swiper-slide>
<swiper-slide>Slide 2</swiper-slide>
<swiper-slide>Slide 3</swiper-slide>
</swiper-container>

// slides.component.ts

import{..., ElementRef, ViewChild}from'@angular/core';

@Component({
...
})
exportclassSlidesExample{
@ViewChild('swiper')
  swiperRef: ElementRef|undefined;

logActiveIndex(){
console.log(this.swiperRef?.nativeElement.swiper.activeIndex);
}
}

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

Effects​

Effects such as Cube or Fade can be used in Swiper Element with no additional imports, as long as you are using the bundled version of Swiper. For example, the below code will cause the slides to have a flip transition effect:

<swiper-containereffect="flip"> ...</swiper-container>

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 Element documentation 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

• Getting Started
• Bundled vs. Core Versions
• Swiping with Style
  • Additionalion-slides Styles
• 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?