Migrating From IonSlides to Swiper.js
IonSlides
?IonSlides
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 React set up in your Ionic Framework application. It will also go over any migration information you may need to move from IonSlides
to the official Swiper React integration.
Swiper's React component is set to be removed in a future release of Swiper, with Swiper Element as the replacement. However, this guide shows how to migrate to the React component because it provides the most stable experience at the time of writing. Notably, React does not have strong support for Web Components yet.
Using Swiper's React component is not required to use Swiper.js with Ionic Framework.
Getting Started
First, update to the latest version of Ionic:
npm install @ionic/react@latest @ionic/react-router@latest
Once that is done, install the Swiper dependency in your project:
npm install swiper@latest
Developers using Create React App must use react-scripts
v5.0.0+ with the latest version of Swiper.
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 with IonSlides
.
We recommend importing the styles in the component in which Swiper is being used. This ensures that the styles are only loaded when needed:
import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';
import 'swiper/css';
import '@ionic/react/css/ionic-swiper.css';
const Home: React.FC = () => {
return (
...
);
};
export default Home;
Importing @ionic/react/css/ionic-swiper.css
is not required to use Swiper.js with Ionic. This files is used for backward-compatibility with the IonSlides
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 target ion-slides
and ion-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 from ion-slides
to Swiper React:
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, replace css
with less
in the Swiper import path:
import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';
import 'swiper/less';
import '@ionic/react/css/ionic-swiper.css';
const Home: React.FC = () => {
return (
...
);
};
export default Home;
For SCSS styles replace css
with scss
in the Swiper import path:
import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';
import 'swiper/scss';
import '@ionic/react/css/ionic-swiper.css';
const Home: React.FC = () => {
return (
...
);
};
export default Home;
Using Components
Swiper exports two components: Swiper
and SwiperSlide
. The Swiper
component is the equivalent of IonSlides
, and SwiperSlide
is the equivalent of IonSlide
.
These components are imported from swiper/react
:
import React from 'react';
import { IonContent, IonPage } from '@ionic/react';
import { Swiper, SwiperSlide } from 'swiper/react';
import 'swiper/css';
import '@ionic/react/css/ionic-swiper.css';
const Home: React.FC = () => {
return (
<IonPage>
<IonContent>
<Swiper>
<SwiperSlide>Slide 1</SwiperSlide>
<SwiperSlide>Slide 2</SwiperSlide>
<SwiperSlide>Slide 3</SwiperSlide>
</Swiper>
</IonContent>
</IonPage>
);
};
export default Home;