Skip to content

docs(slides): update React and Vue migration guides to be compatible with Swiper 9 #2819

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Mar 13, 2023
Merged

docs(slides): update React and Vue migration guides to be compatible with Swiper 9 #2819

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
356f99e
update React docs
Mar 10, 2023
100d3dc
update Vue docs
Mar 13, 2023
e8be80a
typo
Mar 13, 2023
be160b3
revert Vue import changes
Mar 13, 2023
93771af
update custom elements copy
Mar 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 16 additions & 23 deletions docs/react/slides.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Slides
title: Migrating From IonSlides to Swiper.js
---

<head>
Expand All @@ -16,12 +16,13 @@ title: Slides

:::

:::note
This migration guide is compatible with Swiper 8. An updated guide for Swiper 9 is coming soon!
:::
We recommend <a href="http://swiperjs.com/" target="_blank" rel="noopener noreferrer">Swiper.js</a> 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.

:::note
Swiper's React component is set to be removed in a future release of Swiper, with <a href="https://swiperjs.com/element" target="_blank" rel="noopener noreferrer">Swiper Element</a> 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.

We recommend <a href="http://swiperjs.com/" target="_blank" rel="noopener noreferrer">Swiper.js</a> 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.
Using Swiper's React component is **not** required to use Swiper.js with Ionic Framework.
:::

## Getting Started

Expand All @@ -34,7 +35,7 @@ npm install @ionic/react@latest @ionic/react-router@latest
Once that is done, install the Swiper dependency in your project:

```shell
npm install swiper@8
npm install swiper@latest
```

:::note
Expand All @@ -43,7 +44,7 @@ Create React App does not support pure ESM packages yet. Developers can still us

## 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 `ion-slides`.
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:

Expand All @@ -64,13 +65,11 @@ export default Home;
```

:::note
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 `ion-slides` component and can be safely omitted if you prefer not to use the CSS Variables provided in the stylesheet.
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.
:::

:::note

Not using Create React App? You can import the Swiper CSS from `swiper/css` instead.

:::

### Updating Selectors
Expand Down Expand Up @@ -153,16 +152,14 @@ export default Home;
```

:::note

Not using Create React App? You can import the Swiper components from `swiper/react` instead.

:::

## Using Modules

By default, Swiper for React 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.
`IonSlides` 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 the `swiper` package:

Expand Down Expand Up @@ -197,9 +194,7 @@ export default Home;
```

:::note

Not using Create React App? You can import these modules from `swiper/css/[MODULE NAME]` instead (i.e. `swiper/css/autoplay`).

:::

From here, we need to provide these modules to Swiper by using the `modules` property on the `Swiper` component:
Expand Down Expand Up @@ -279,7 +274,7 @@ See <a href="https://swiperjs.com/react#usage" target="_blank" rel="noopener nor

## The IonicSlides Module

With `ion-slides`, Ionic automatically customized dozens of Swiper properties. This resulted in an experience that felt smooth when swiping on mobile devices. We recommend using the `IonicSlides` module to ensure that these properties are also set when using Swiper directly. However, using this module is **not** required to use Swiper.js in Ionic.
With `IonSlides`, Ionic automatically customized dozens of Swiper properties. This resulted in an experience that felt smooth when swiping on mobile devices. We recommend using the `IonicSlides` module to ensure that these properties are also set when using Swiper directly. However, using this module is **not** required to use Swiper.js in Ionic.

We can install the `IonicSlides` module by importing it from `@ionic/react` and passing it in as the last item in the `modules` array:

Expand Down Expand Up @@ -428,7 +423,7 @@ Below is a full list of event name changes when going from `IonSlides` to Swiper
| onIonSlidesDidLoad | onInit |

:::note
All events available in Swiper React can be found at <a href="https://swiperjs.com/react#swiper-events" target="_blank" rel="noopener noreferrer">https://swiperjs.com/react#swiper-events</a>.
All events available in Swiper can be found at <a href="https://swiperjs.com/swiper-api#events" target="_blank" rel="noopener noreferrer">https://swiperjs.com/swiper-api#events</a>.
:::

## Methods
Expand Down Expand Up @@ -460,7 +455,7 @@ From here, if you wanted to access a property on the Swiper instance you would a

Below is a full list of method changes when going from `IonSlides` to Swiper React:

| ion-slides Method | Notes |
| IonSlides Method | Notes |
| ------------------ | ------------------------------------------------------------------------------------ |
| getActiveIndex() | Use the `activeIndex` property instead. |
| getPreviousIndex() | Use the `previousIndex` property instead. |
Expand Down Expand Up @@ -491,7 +486,7 @@ const Home: React.FC = () => {
return (
<IonPage>
<IonContent>
<Swiper modules={[EffectFact, IonicSlides]}>
<Swiper modules={[EffectFade, IonicSlides]}>
<SwiperSlide>Slide 1</SwiperSlide>
<SwiperSlide>Slide 2</SwiperSlide>
<SwiperSlide>Slide 3</SwiperSlide>
Expand Down Expand Up @@ -519,7 +514,7 @@ const Home: React.FC = () => {
return (
<IonPage>
<IonContent>
<Swiper modules={[EffectFact, IonicSlides]}>
<Swiper modules={[EffectFade, IonicSlides]}>
<SwiperSlide>Slide 1</SwiperSlide>
<SwiperSlide>Slide 2</SwiperSlide>
<SwiperSlide>Slide 3</SwiperSlide>
Expand All @@ -532,9 +527,7 @@ export default Home;
```

:::note

Not using Create React App? You can import these effects from `swiper/css/[EFFECT NAME]` instead (i.e. `swiper/css/effect-fade`).

:::

After that, we can activate it by setting the `effect` property on `swiper` to `"fade"`:
Expand All @@ -553,7 +546,7 @@ const Home: React.FC = () => {
return (
<IonPage>
<IonContent>
<Swiper modules={[EffectFact, IonicSlides]} swiper="fade">
<Swiper modules={[EffectFade, IonicSlides]} effect="fade">
<SwiperSlide>Slide 1</SwiperSlide>
<SwiperSlide>Slide 2</SwiperSlide>
<SwiperSlide>Slide 3</SwiperSlide>
Expand Down
17 changes: 8 additions & 9 deletions docs/vue/slides.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Slides
title: Migrating From ion-slides to Swiper.js
---

<head>
Expand All @@ -11,17 +11,16 @@ title: Slides
</head>

:::caution Looking for `ion-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.

:::

:::note
This migration guide is compatible with Swiper 8. An updated guide for Swiper 9 is coming soon!
:::
We recommend <a href="http://swiperjs.com/" target="_blank" rel="noopener noreferrer">Swiper.js</a> 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 from `ion-slides` to the official Swiper Vue integration.

:::note
Swiper's Vue component is set to be removed in a future release of Swiper, with <a href="https://swiperjs.com/element" target="_blank" rel="noopener noreferrer">Swiper Element</a> 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.

We recommend <a href="http://swiperjs.com/" target="_blank" rel="noopener noreferrer">Swiper.js</a> 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 from `ion-slides` to the official Swiper Vue integration.
Using Swiper's Vue component is **not** required to use Swiper.js with Ionic Framework.
:::

## Getting Started

Expand All @@ -40,7 +39,7 @@ vue upgrade --next
Once that is done, install the Swiper dependency in your project:

```shell
npm install swiper@8
npm install swiper@latest
```

## Swiping with Style
Expand All @@ -63,7 +62,7 @@ We recommend importing the styles in the component in which Swiper is being used
```

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

### Updating Selectors
Expand Down
40 changes: 17 additions & 23 deletions versioned_docs/version-v6/react/slides.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Slides
title: Migrating From IonSlides to Swiper.js
---

<head>
Expand All @@ -10,14 +10,16 @@ title: Slides
/>
</head>

:::note
This migration guide is compatible with Swiper 8. An updated guide for Swiper 9 is coming soon!
:::

We recommend <a href="http://swiperjs.com/" target="_blank" rel="noopener noreferrer">Swiper.js</a> if you need a modern touch slider component. It powers our `IonSlides` component, but we now recommend that developers use Swiper for React directly.

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.

:::note
Swiper's React component is set to be removed in a future release of Swiper, with <a href="https://swiperjs.com/element" target="_blank" rel="noopener noreferrer">Swiper Element</a> 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:
Expand All @@ -29,7 +31,7 @@ npm install @ionic/react@latest @ionic/react-router@latest
Once that is done, install the Swiper dependency in your project:

```shell
npm install swiper@8
npm install swiper@latest
```

:::note
Expand All @@ -38,7 +40,7 @@ Create React App does not support pure ESM packages yet. Developers can still us

## 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 `ion-slides`.
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:

Expand All @@ -59,13 +61,11 @@ export default Home;
```

:::note
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 `ion-slides` component and can be safely omitted if you prefer not to use the CSS Variables provided in the stylesheet.
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.
:::

:::note

Not using Create React App? You can import the Swiper CSS from `swiper/css` instead.

:::

### Updating Selectors
Expand Down Expand Up @@ -148,16 +148,14 @@ export default Home;
```

:::note

Not using Create React App? You can import the Swiper components from `swiper/react` instead.

:::

## Using Modules

By default, Swiper for React 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.
`IonSlides` 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 the `swiper` package:

Expand Down Expand Up @@ -192,9 +190,7 @@ export default Home;
```

:::note

Not using Create React App? You can import these modules from `swiper/css/[MODULE NAME]` instead (i.e. `swiper/css/autoplay`).

:::

From here, we need to provide these modules to Swiper by using the `modules` property on the `Swiper` component:
Expand Down Expand Up @@ -274,7 +270,7 @@ See <a href="https://swiperjs.com/react#usage" target="_blank" rel="noopener nor

## The IonicSlides Module

With `ion-slides`, Ionic automatically customized dozens of Swiper properties. This resulted in an experience that felt smooth when swiping on mobile devices. We recommend using the `IonicSlides` module to ensure that these properties are also set when using Swiper directly. However, using this module is **not** required to use Swiper.js in Ionic.
With `IonSlides`, Ionic automatically customized dozens of Swiper properties. This resulted in an experience that felt smooth when swiping on mobile devices. We recommend using the `IonicSlides` module to ensure that these properties are also set when using Swiper directly. However, using this module is **not** required to use Swiper.js in Ionic.

We can install the `IonicSlides` module by importing it from `@ionic/react` and passing it in as the last item in the `modules` array:

Expand Down Expand Up @@ -423,7 +419,7 @@ Below is a full list of event name changes when going from `IonSlides` to Swiper
| onIonSlidesDidLoad | onInit |

:::note
All events available in Swiper React can be found at <a href="https://swiperjs.com/react#swiper-events" target="_blank" rel="noopener noreferrer">https://swiperjs.com/react#swiper-events</a>.
All events available in Swiper can be found at <a href="https://swiperjs.com/swiper-api#events" target="_blank" rel="noopener noreferrer">https://swiperjs.com/swiper-api#events</a>.
:::

## Methods
Expand Down Expand Up @@ -455,7 +451,7 @@ From here, if you wanted to access a property on the Swiper instance you would a

Below is a full list of method changes when going from `IonSlides` to Swiper React:

| ion-slides Method | Notes |
| IonSlides Method | Notes |
| ------------------ | ------------------------------------------------------------------------------------ |
| getActiveIndex() | Use the `activeIndex` property instead. |
| getPreviousIndex() | Use the `previousIndex` property instead. |
Expand Down Expand Up @@ -486,7 +482,7 @@ const Home: React.FC = () => {
return (
<IonPage>
<IonContent>
<Swiper modules={[EffectFact, IonicSlides]}>
<Swiper modules={[EffectFade, IonicSlides]}>
<SwiperSlide>Slide 1</SwiperSlide>
<SwiperSlide>Slide 2</SwiperSlide>
<SwiperSlide>Slide 3</SwiperSlide>
Expand Down Expand Up @@ -514,7 +510,7 @@ const Home: React.FC = () => {
return (
<IonPage>
<IonContent>
<Swiper modules={[EffectFact, IonicSlides]}>
<Swiper modules={[EffectFade, IonicSlides]}>
<SwiperSlide>Slide 1</SwiperSlide>
<SwiperSlide>Slide 2</SwiperSlide>
<SwiperSlide>Slide 3</SwiperSlide>
Expand All @@ -527,9 +523,7 @@ export default Home;
```

:::note

Not using Create React App? You can import these effects from `swiper/css/[EFFECT NAME]` instead (i.e. `swiper/css/effect-fade`).

:::

After that, we can activate it by setting the `effect` property on `swiper` to `"fade"`:
Expand All @@ -548,7 +542,7 @@ const Home: React.FC = () => {
return (
<IonPage>
<IonContent>
<Swiper modules={[EffectFact, IonicSlides]} swiper="fade">
<Swiper modules={[EffectFade, IonicSlides]} effect="fade">
<SwiperSlide>Slide 1</SwiperSlide>
<SwiperSlide>Slide 2</SwiperSlide>
<SwiperSlide>Slide 3</SwiperSlide>
Expand Down
16 changes: 9 additions & 7 deletions versioned_docs/version-v6/vue/slides.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Slides
title: Migrating From ion-slides to Swiper.js
---

<head>
Expand All @@ -10,14 +10,16 @@ title: Slides
/>
</head>

:::note
This migration guide is compatible with Swiper 8. An updated guide for Swiper 9 is coming soon!
:::

We recommend <a href="http://swiperjs.com/" target="_blank" rel="noopener noreferrer">Swiper.js</a> if you need a modern touch slider component. It powers our `ion-slides` component, but we now recommend that developers use Swiper for Vue directly.

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 from `ion-slides` to the official Swiper Vue integration.

:::note
Swiper's Vue component is set to be removed in a future release of Swiper, with <a href="https://swiperjs.com/element" target="_blank" rel="noopener noreferrer">Swiper Element</a> 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 is **not** required to use Swiper.js with Ionic Framework.
:::

## Getting Started

First, update to the latest version of Ionic:
Expand All @@ -35,7 +37,7 @@ vue upgrade --next
Once that is done, install the Swiper dependency in your project:

```shell
npm install swiper@8
npm install swiper@latest
```

## Swiping with Style
Expand All @@ -58,7 +60,7 @@ We recommend importing the styles in the component in which Swiper is being used
```

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

### Updating Selectors
Expand Down