From 83fee93801c6ea922a78421e74e02827da329f4d Mon Sep 17 00:00:00 2001 From: amandaesmith333 Date: Tue, 14 Mar 2023 14:25:06 -0500 Subject: [PATCH 1/3] update Angular docs --- docs/angular/slides.md | 396 +++++++------------ versioned_docs/version-v6/angular/slides.md | 398 +++++++------------- 2 files changed, 280 insertions(+), 514 deletions(-) diff --git a/docs/angular/slides.md b/docs/angular/slides.md index 746be513f1c..02e900c7a18 100644 --- a/docs/angular/slides.md +++ b/docs/angular/slides.md @@ -1,5 +1,5 @@ --- -title: Slides +title: Migrating from ion-slides to Swiper.js --- @@ -11,16 +11,10 @@ title: Slides :::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 Swiper.js if you need a modern touch slider component. This guide will go over how to get Swiper for Angular 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 Angular integration. +We recommend Swiper.js if you need a modern touch slider component. Swiper 9 introduced Swiper 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 from `ion-slides` to Swiper Element. ## Getting Started @@ -33,180 +27,139 @@ npm install @ionic/angular@latest Once that is done, install the Swiper dependency in your project: ```shell -npm install swiper@8 +npm install swiper@latest ``` -Once that is done, we need to import the `SwiperModule` module. This should be done in your component's module file: +Next, we need to add the `CUSTOM_ELEMENTS_SCHEMA`, which tells Angular that we will be using custom elements. This can be done in either `app.module.ts`, or the module file for the component where you will be using Swiper. ```typescript -// home.module.ts -import { SwiperModule } from 'swiper/angular'; +import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; @NgModule({ - imports: [..., SwiperModule] + schemas: [..., CUSTOM_ELEMENTS_SCHEMA] }); ... ``` -## 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`. - -You can import these files in `global.scss`: - -```scss -// global.scss -@import '~swiper/scss'; -@import '~@ionic/angular/css/ionic-swiper'; -``` - -If you prefer to import these in the CSS file for your slides component, you will need to disable [ViewEncapsulation in Angular](https://angular.io/api/core/ViewEncapsulation), otherwise the styles will not apply: +Finally, we need to call Swiper's `register` function to globally register Swiper's custom elements. This should only be done once, so place it in `app.component.ts`. ```typescript -// home.page.ts -import { Component, ViewEncapsulation } from '@angular/core'; +import { register } from 'swiper/element/bundle'; + +register(); @Component({ - selector: 'app-home', - templateUrl: 'home.page.html', - styleUrls: ['home.page.scss'], - encapsulation: ViewEncapsulation.None -}) -export class HomePage { ... -} +}) +... ``` -```scss -// home.page.scss -@import '~swiper/scss'; -@import '~@ionic/angular/css/ionic-swiper'; +From there, we just have to replace `ion-slides` elements with `swiper-container` and `ion-slide` elements with `swiper-slide`. Note that these custom elements do not need to be imported, as calling `register` tells Angular about them on its own. + +```typescript + + Slide 1 + Slide 2 + Slide 3 + ``` -:::note -Importing `@ionic/angular/css/ionic-swiper'` 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. -::: +## Bundled vs. Core Versions -### Updating Selectors +By default, make sure you import the `register` function from `swiper/element/bundle`. This uses the bundled version of Swiper, which automatically includes all modules and stylesheets needed to run Swiper's various features. -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 Angular: +If you would like to use the Core version instead, which does not include additional modules automatically, see https://swiperjs.com/element#core-version-and-modules. The rest of this migration guide will assume you are using the bundled version. -| ion-slides Selector | Swiper Selector | -| ------------------- | --------------- | -| `ion-slides` | `.swiper` | -| `ion-slide` | `.swiper-slide` | +## Swiping with Style -### Vanilla CSS (Optional) +To migrate over your CSS, first update your selectors to target the new custom elements instead: -For developers not using a CSS pre-processor, Swiper also provides the styles bundled together. It is important to note that this will import styles for all modules as well. +| ion-slides Selector | Swiper Selector | +| ------------------- | ------------------ | +| `ion-slides` | `swiper-container` | +| `ion-slide` | `swiper-slide` | -```javascript -// slides.component.css -@import 'swiper/css'; -@import '@ionic/angular/css/ionic-swiper'; -``` +If you were using the CSS custom properties found on `ion-slides`, below is a list of corresponding properties used in Swiper. -## Using Components +| `ion-slides` CSS property | `swiper-container` CSS property | +| ---------------------------------- | ------------------------------------------- | +| `--bullet-background` | `--swiper-pagination-bullet-inactive-color` | +| `--bullet-background-active` | `--swiper-pagination-color` | +| `--progress-bar-background` | `--swiper-pagination-progressbar-bg-color` | +| `--progress-bar-background-active` | `--swiper-pagination-color` | +| `--scroll-bar-background` | `--swiper-scrollbar-bg-color` | +| `--scroll-bar-background-active` | `--swiper-scrollbar-drag-bg-color` | -Swiper Angular exports a `Swiper` component which is the equivalent of `ion-slides`. It also exports a `swiperSlide` directive which can be used on an `` for each slide: +For additional custom CSS, because Swiper Element uses Shadow DOM encapsulation, styles will need to be injected into the Shadow DOM scope. See see https://swiperjs.com/element#injecting-styles for instructions. -```html - - - - Slide 1 - Slide 2 - Slide 3 - - -``` +### Additional `ion-slides` Styles -## Using Modules +The `ion-slides` component had additional styling that helped create a native look and feel. These styles are **not** required to use Swiper.js with Ionic, but if you would like to maintain the look of `ion-slides` as closely as possible, add the following CSS to your `global.scss`: -By default, Swiper for Angular does not import any additional modules. To use modules such as Navigation or Pagination, you need to import them first. +```css +swiper-container { + --swiper-pagination-bullet-inactive-color: var(--ion-color-step-200, #cccccc); + --swiper-pagination-color: var(--ion-color-primary, #3880ff); + --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); +} -`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. +swiper-slide { + display: flex; + position: relative; -To begin, we need to import the modules and provide them to Swiper: + flex-shrink: 0; + align-items: center; + justify-content: center; -```typescript -// home.page.ts -import { Component } from '@angular/core'; -import SwiperCore, { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper'; + width: 100%; + height: 100%; -SwiperCore.use([Autoplay, Keyboard, Pagination, Scrollbar, Zoom]); + font-size: 18px; -@Component({ - selector: 'app-home', - templateUrl: 'home.page.html', - styleUrls: ['home.page.scss'] -}) -export class HomePage { - ... + text-align: center; + box-sizing: border-box; } -``` -Next, we need to import the stylesheets for each module: - -```scss -// global.scss -@import '~swiper/scss'; -@import '~swiper/scss/autoplay'; -@import '~swiper/scss/keyboard'; -@import '~swiper/scss/pagination'; -@import '~swiper/scss/scrollbar'; -@import '~swiper/scss/zoom'; -@import '~@ionic/angular/css/ionic-swiper'; -``` - -Finally, we can turn these features on by using the appropriate properties: - -```html - - - - Slide 1 - Slide 2 - Slide 3 - - +swiper-slide img { + width: auto; + max-width: 100%; + height: auto; + max-height: 100%; +} ``` -:::note -See https://swiperjs.com/angular#usage for a full list of modules. -::: - ## 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. -We can install the `IonicSlides` module by importing it from `@ionic/angular` and passing it in as the last item in the array provided in `SwiperCore.use`: +We can install the `IonicSlides` module by importing it from `@ionic/angular` and passing it to the `modules` property of `swiper-container` as an array: -```javascript +```typescript // home.page.ts -import { Component } from '@angular/core'; -import SwiperCore, { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper'; import { IonicSlides } from '@ionic/angular'; -SwiperCore.use([Autoplay, Keyboard, Pagination, Scrollbar, Zoom, IonicSlides]); - @Component({ - selector: 'app-home', - templateUrl: 'home.page.html', - styleUrls: ['home.page.scss'] + ... }) export class HomePage { - ... + swiperModules = [IonicSlides]; } + +// home.page.html + + ... + ``` :::note -The `IonicSlides` 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. +If you are using the Core version of Swiper and have installed additional modules, ensure that `IonicSlides` is 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 can be provided as individual properties directly on the `` component or via the `config` property. +Swiper options should be provided as individual properties directly on the `` component. Let's say in an app with `ion-slides` we had the `slidesPerView` and `loop` options set: @@ -218,42 +171,31 @@ Let's say in an app with `ion-slides` we had the `slidesPerView` and `loop` opti ``` -To set these options as properties directly on `` we would do the following: - -```html - - Slide 1 - Slide 2 - Slide 3 - -``` - -To set these options using the `config` object, we would do: +To set these options as properties directly on `` we would do the following: ```html - - Slide 1 - Slide 3 - Slide 3 - + + Slide 1 + Slide 2 + Slide 3 + ``` -Below is a full list of property changes when going from `ion-slides` to Swiper Angular: +Below is a full list of property changes when going from `ion-slides` to Swiper Element: -| Name | Notes | -| --------- | --------------------------------------------------------------------------------------------------------------------- | -| options | Use the `config` property instead or set each option as a property directly on the `` 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. | +| Name | Notes | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| options | Set each option as a property directly on the `` component. | +| mode | For different styles based upon the mode, you can target the slides with `.ios swiper-container` or `.md swiper-container` in your CSS. | +| pager | Use the `pagination` property instead. | :::note -All properties available in Swiper Angular can be found at https://swiperjs.com/angular#swiper-component-props. +All properties available in Swiper Element can be found at https://swiperjs.com/swiper-api#parameters. ::: ## Events -Since the `Swiper` component is not provided by Ionic Framework, event names will not have an `ionSlide` prefix to them. +Since the `swiper-container` component is not provided by Ionic Framework, event names will not have an `ionSlide` prefix to them. Additionally, all event names should be lowercase instead of camelCase. Let's say in an app with `ion-slides` we used the `ionSlideDidChange` event: @@ -265,170 +207,110 @@ Let's say in an app with `ion-slides` we used the `ionSlideDidChange` event: ``` -To migrate, we would change the name of the event to `slideChange`: +To migrate, we would change the name of the event to `slidechange`: ```html - - Slide 1 - Slide 2 - Slide 3 - + + Slide 1 + Slide 2 + Slide 3 + ``` Below is a full list of event name changes when going from `ion-slides` to Swiper Angular: | 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 | +| 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 | +| ionSlideTouchStart | touchstart | +| ionSlideTouchEnd | touchend | +| ionSlideTransitionStart | transitionstart | +| ionSlideTransitionEnd | transitionend | | ionSlidesDidLoad | init | :::note -All events available in Swiper Angular can be found at https://swiperjs.com/angular#swiper-component-events. +All events available in Swiper Element can be found at https://swiperjs.com/swiper-api#events. ::: ## Methods -Most methods have been removed in favor of accessing the `` props directly. - -Accessing these properties can be tricky as you want to access the properties on the Swiper instance itself, not your Angular component. To do this, we recommend getting a reference to the `Swiper` instance via `(swiper)`: +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 `` element (such as through `ViewChild`), then access its `swiper` prop: ```html - - Slide 1 - Slide 2 - Slide 3 - + + Slide 1 + Slide 2 + Slide 3 + ``` -```javascript +```typescript // slides.component.ts -import { Component } from '@angular/core'; + +import { ..., ElementRef, ViewChild } from '@angular/core'; @Component({ - selector: 'app-slides-example', - templateUrl: 'slides.component.html', - styleUrls: ['slides.component.scss'] + ... }) export class SlidesExample { - private slides: any; + @ViewChild('swiper') + swiperRef: ElementRef | undefined; - constructor() {} - setSwiperInstance(swiper: any) { - this.slides = swiper; + logActiveIndex() { + console.log(this.swiperRef?.nativeElement.swiper.activeIndex); } } ``` -From here, if you wanted to access a property on the Swiper instance you would access `this.slides`. For example, if you wanted to check the `isBeginning` property, you could do: `this.slides.isBeginning`. Make sure `this.slides` is defined first though! - -Below is a full list of method changes when going from `ion-slides` to Swiper Angular: +Below is a full list of method changes when going from `ion-slides` to Swiper Element: | 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. | +| getSwiper() | Get a reference to the Swiper instance using the `swiper` prop. 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) | +| length() | Use the `slides` property instead. (i.e swiper.slides.length) | | lockSwipeToNext() | Use the `allowSlidesNext` 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 import the `EffectFade` module and register it using `SwiperCore.use`: - -```html - - - - Slide 1 - Slide 2 - Slide 3 - -``` - -```javascript -// slides.component.ts -import { Component } from '@angular/core'; -import SwiperCore, { EffectFade } from 'swiper'; -import { IonicSlides } from '@ionic/angular'; - -SwiperCore.use([EffectFade, IonicSlides]); - -@Component({ - selector: 'app-slides-example', - templateUrl: 'slides.component.html', - styleUrls: ['slides.component.scss'], -}) -export class SlidesExample { - constructor() {} -} -``` - -Next, we need to import the stylesheet associated with the effect: +:::note +All methods and properties available on the Swiper instance can be found at https://swiperjs.com/swiper-api#methods-and-properties. +::: -```scss -// global.scss -@import '~swiper/scss/effect-fade'; -``` +## Effects -After that, we can activate it by setting the `effect` property on `swiper` to `"fade"`: +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: ```html - - - - Slide 1 - Slide 2 - Slide 3 - -``` - -```javascript -// slides.component.ts -import { Component } from '@angular/core'; -import SwiperCore, { EffectFade } from 'swiper'; -import { IonicSlides } from '@ionic/angular'; - -SwiperCore.use([EffectFade, IonicSlides]); - -@Component({ - selector: 'app-slides-example', - templateUrl: 'slides.component.html', - styleUrls: ['slides.component.scss'], -}) -export class SlidesExample { - constructor() {} -} + + ... + ``` :::note -For more information on effects in Swiper, please see https://swiperjs.com/angular#effects. +For more information on effects in Swiper, please see https://swiperjs.com/swiper-api#fade-effect. ::: ## 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 the Swiper Angular Introduction and then referencing the Swiper API docs. +Now that you have Swiper installed, there is a whole set of new Swiper features for you to enjoy. We recommend starting with the Swiper Element documentation and then referencing the Swiper API docs. ## FAQ diff --git a/versioned_docs/version-v6/angular/slides.md b/versioned_docs/version-v6/angular/slides.md index 872b5eaae92..ef1c951984f 100644 --- a/versioned_docs/version-v6/angular/slides.md +++ b/versioned_docs/version-v6/angular/slides.md @@ -1,5 +1,5 @@ --- -title: Slides +title: Migrating from ion-slides to Swiper.js --- @@ -10,13 +10,9 @@ title: Slides /> -:::note -This migration guide is compatible with Swiper 8. An updated guide for Swiper 9 is coming soon! -::: - -We recommend Swiper.js if you need a modern touch slider component. It powers our `ion-slides` component, but we now recommend that developers use Swiper for Angular directly. +We recommend Swiper.js if you need a modern touch slider component. It powers our `ion-slides` component, but we now recommend that developers use Swiper directly. -This guide will go over how to get Swiper for Angular 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 Angular integration. +Swiper 9 introduced Swiper 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 from `ion-slides` to Swiper Element. ## Getting Started @@ -29,180 +25,139 @@ npm install @ionic/angular@latest Once that is done, install the Swiper dependency in your project: ```shell -npm install swiper@8 +npm install swiper@latest ``` -Once that is done, we need to import the `SwiperModule` module. This should be done in your component's module file: +Next, we need to add the `CUSTOM_ELEMENTS_SCHEMA`, which tells Angular that we will be using custom elements. This can be done in either `app.module.ts`, or the module file for the component where you will be using Swiper. ```typescript -// home.module.ts -import { SwiperModule } from 'swiper/angular'; +import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; @NgModule({ - imports: [..., SwiperModule] + schemas: [..., CUSTOM_ELEMENTS_SCHEMA] }); ... ``` -## Swiping with Style +Finally, we need to call Swiper's `register` function to globally register Swiper's custom elements. This should only be done once, so place it in `app.component.ts`. -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`. +```typescript +import { register } from 'swiper/element/bundle'; -You can import these files in `global.scss`: +register(); -```scss -// global.scss -@import '~swiper/scss'; -@import '~@ionic/angular/css/ionic-swiper'; +@Component({ + ... +}) +... ``` -If you prefer to import these in the CSS file for your slides component, you will need to disable [ViewEncapsulation in Angular](https://angular.io/api/core/ViewEncapsulation), otherwise the styles will not apply: +From there, we just have to replace `ion-slides` elements with `swiper-container` and `ion-slide` elements with `swiper-slide`. Note that these custom elements do not need to be imported, as calling `register` tells Angular about them on its own. ```typescript -// home.page.ts -import { Component, ViewEncapsulation } from '@angular/core'; - -@Component({ - selector: 'app-home', - templateUrl: 'home.page.html', - styleUrls: ['home.page.scss'], - encapsulation: ViewEncapsulation.None -}) -export class HomePage { - ... -} + + Slide 1 + Slide 2 + Slide 3 + ``` -```scss -// home.page.scss -@import '~swiper/scss'; -@import '~@ionic/angular/css/ionic-swiper'; -``` +## Bundled vs. Core Versions -:::note -Importing `@ionic/angular/css/ionic-swiper'` 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. -::: +By default, make sure you import the `register` function from `swiper/element/bundle`. This uses the bundled version of Swiper, which automatically includes all modules and stylesheets needed to run Swiper's various features. -### Updating Selectors +If you would like to use the Core version instead, which does not include additional modules automatically, see https://swiperjs.com/element#core-version-and-modules. The rest of this migration guide will assume you are using the bundled version. -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 Angular: +## Swiping with Style -| ion-slides Selector | Swiper Selector | -| ------------------- | --------------- | -| `ion-slides` | `.swiper` | -| `ion-slide` | `.swiper-slide` | +To migrate over your CSS, first update your selectors to target the new custom elements instead: -### Vanilla CSS (Optional) +| ion-slides Selector | Swiper Selector | +| ------------------- | ------------------ | +| `ion-slides` | `swiper-container` | +| `ion-slide` | `swiper-slide` | -For developers not using a CSS pre-processor, Swiper also provides the styles bundled together. It is important to note that this will import styles for all modules as well. +If you were using the CSS custom properties found on `ion-slides`, below is a list of corresponding properties used in Swiper. -```javascript -// slides.component.css -@import 'swiper/css'; -@import '@ionic/angular/css/ionic-swiper'; -``` +| `ion-slides` CSS property | `swiper-container` CSS property | +| ---------------------------------- | ------------------------------------------- | +| `--bullet-background` | `--swiper-pagination-bullet-inactive-color` | +| `--bullet-background-active` | `--swiper-pagination-color` | +| `--progress-bar-background` | `--swiper-pagination-progressbar-bg-color` | +| `--progress-bar-background-active` | `--swiper-pagination-color` | +| `--scroll-bar-background` | `--swiper-scrollbar-bg-color` | +| `--scroll-bar-background-active` | `--swiper-scrollbar-drag-bg-color` | -## Using Components +For additional custom CSS, because Swiper Element uses Shadow DOM encapsulation, styles will need to be injected into the Shadow DOM scope. See see https://swiperjs.com/element#injecting-styles for instructions. -Swiper Angular exports a `Swiper` component which is the equivalent of `ion-slides`. It also exports a `swiperSlide` directive which can be used on an `` for each slide: +### Additional `ion-slides` Styles -```html - - - - Slide 1 - Slide 2 - Slide 3 - - -``` +The `ion-slides` component had additional styling that helped create a native look and feel. These styles are **not** required to use Swiper.js with Ionic, but if you would like to maintain the look of `ion-slides` as closely as possible, add the following CSS to your `global.scss`: -## Using Modules - -By default, Swiper for Angular does not import any additional modules. To use modules such as Navigation or Pagination, you need to import them first. +```css +swiper-container { + --swiper-pagination-bullet-inactive-color: var(--ion-color-step-200, #cccccc); + --swiper-pagination-color: var(--ion-color-primary, #3880ff); + --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); +} -`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. +swiper-slide { + display: flex; + position: relative; -To begin, we need to import the modules and provide them to Swiper: + flex-shrink: 0; + align-items: center; + justify-content: center; -```typescript -// home.page.ts -import { Component } from '@angular/core'; -import SwiperCore, { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper'; + width: 100%; + height: 100%; -SwiperCore.use([Autoplay, Keyboard, Pagination, Scrollbar, Zoom]); + font-size: 18px; -@Component({ - selector: 'app-home', - templateUrl: 'home.page.html', - styleUrls: ['home.page.scss'] -}) -export class HomePage { - ... + text-align: center; + box-sizing: border-box; } -``` - -Next, we need to import the stylesheets for each module: - -```scss -// global.scss -@import '~swiper/scss'; -@import '~swiper/scss/autoplay'; -@import '~swiper/scss/keyboard'; -@import '~swiper/scss/pagination'; -@import '~swiper/scss/scrollbar'; -@import '~swiper/scss/zoom'; -@import '~@ionic/angular/css/ionic-swiper'; -``` -Finally, we can turn these features on by using the appropriate properties: - -```html - - - - Slide 1 - Slide 2 - Slide 3 - - +swiper-slide img { + width: auto; + max-width: 100%; + height: auto; + max-height: 100%; +} ``` -:::note -See https://swiperjs.com/angular#usage for a full list of modules. -::: - ## 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. -We can install the `IonicSlides` module by importing it from `@ionic/angular` and passing it in as the last item in the array provided in `SwiperCore.use`: +We can install the `IonicSlides` module by importing it from `@ionic/angular` and passing it to the `modules` property of `swiper-container` as an array: -```javascript +```typescript // home.page.ts -import { Component } from '@angular/core'; -import SwiperCore, { Autoplay, Keyboard, Pagination, Scrollbar, Zoom } from 'swiper'; import { IonicSlides } from '@ionic/angular'; -SwiperCore.use([Autoplay, Keyboard, Pagination, Scrollbar, Zoom, IonicSlides]); - @Component({ - selector: 'app-home', - templateUrl: 'home.page.html', - styleUrls: ['home.page.scss'] + ... }) export class HomePage { - ... + swiperModules = [IonicSlides]; } + +// home.page.html + + ... + ``` :::note -The `IonicSlides` 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. +If you are using the Core version of Swiper and have installed additional modules, ensure that `IonicSlides` is 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 can be provided as individual properties directly on the `` component or via the `config` property. +Swiper options should be provided as individual properties directly on the `` component. Let's say in an app with `ion-slides` we had the `slidesPerView` and `loop` options set: @@ -214,42 +169,31 @@ Let's say in an app with `ion-slides` we had the `slidesPerView` and `loop` opti ``` -To set these options as properties directly on `` we would do the following: - -```html - - Slide 1 - Slide 2 - Slide 3 - -``` - -To set these options using the `config` object, we would do: +To set these options as properties directly on `` we would do the following: ```html - - Slide 1 - Slide 3 - Slide 3 - + + Slide 1 + Slide 2 + Slide 3 + ``` -Below is a full list of property changes when going from `ion-slides` to Swiper Angular: +Below is a full list of property changes when going from `ion-slides` to Swiper Element: -| Name | Notes | -| --------- | --------------------------------------------------------------------------------------------------------------------- | -| options | Use the `config` property instead or set each option as a property directly on the `` 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. | +| Name | Notes | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| options | Set each option as a property directly on the `` component. | +| mode | For different styles based upon the mode, you can target the slides with `.ios swiper-container` or `.md swiper-container` in your CSS. | +| pager | Use the `pagination` property instead. | :::note -All properties available in Swiper Angular can be found at https://swiperjs.com/angular#swiper-component-props. +All properties available in Swiper Element can be found at https://swiperjs.com/swiper-api#parameters. ::: ## Events -Since the `Swiper` component is not provided by Ionic Framework, event names will not have an `ionSlide` prefix to them. +Since the `swiper-container` component is not provided by Ionic Framework, event names will not have an `ionSlide` prefix to them. Additionally, all event names should be lowercase instead of camelCase. Let's say in an app with `ion-slides` we used the `ionSlideDidChange` event: @@ -261,170 +205,110 @@ Let's say in an app with `ion-slides` we used the `ionSlideDidChange` event: ``` -To migrate, we would change the name of the event to `slideChange`: +To migrate, we would change the name of the event to `slidechange`: ```html - - Slide 1 - Slide 2 - Slide 3 - + + Slide 1 + Slide 2 + Slide 3 + ``` Below is a full list of event name changes when going from `ion-slides` to Swiper Angular: | 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 | +| 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 | +| ionSlideTouchStart | touchstart | +| ionSlideTouchEnd | touchend | +| ionSlideTransitionStart | transitionstart | +| ionSlideTransitionEnd | transitionend | | ionSlidesDidLoad | init | :::note -All events available in Swiper Angular can be found at https://swiperjs.com/angular#swiper-component-events. +All events available in Swiper Element can be found at https://swiperjs.com/swiper-api#events. ::: ## Methods -Most methods have been removed in favor of accessing the `` props directly. - -Accessing these properties can be tricky as you want to access the properties on the Swiper instance itself, not your Angular component. To do this, we recommend getting a reference to the `Swiper` instance via `(swiper)`: +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 `` element (such as through `ViewChild`), then access its `swiper` prop: ```html - - Slide 1 - Slide 2 - Slide 3 - + + Slide 1 + Slide 2 + Slide 3 + ``` -```javascript +```typescript // slides.component.ts -import { Component } from '@angular/core'; + +import { ..., ElementRef, ViewChild } from '@angular/core'; @Component({ - selector: 'app-slides-example', - templateUrl: 'slides.component.html', - styleUrls: ['slides.component.scss'] + ... }) export class SlidesExample { - private slides: any; + @ViewChild('swiper') + swiperRef: ElementRef | undefined; - constructor() {} - setSwiperInstance(swiper: any) { - this.slides = swiper; + logActiveIndex() { + console.log(this.swiperRef?.nativeElement.swiper.activeIndex); } } ``` -From here, if you wanted to access a property on the Swiper instance you would access `this.slides`. For example, if you wanted to check the `isBeginning` property, you could do: `this.slides.isBeginning`. Make sure `this.slides` is defined first though! - -Below is a full list of method changes when going from `ion-slides` to Swiper Angular: +Below is a full list of method changes when going from `ion-slides` to Swiper Element: | 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. | +| getSwiper() | Get a reference to the Swiper instance using the `swiper` prop. 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) | +| length() | Use the `slides` property instead. (i.e swiper.slides.length) | | lockSwipeToNext() | Use the `allowSlidesNext` 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 import the `EffectFade` module and register it using `SwiperCore.use`: - -```html - - - - Slide 1 - Slide 2 - Slide 3 - -``` - -```javascript -// slides.component.ts -import { Component } from '@angular/core'; -import SwiperCore, { EffectFade } from 'swiper'; -import { IonicSlides } from '@ionic/angular'; - -SwiperCore.use([EffectFade, IonicSlides]); - -@Component({ - selector: 'app-slides-example', - templateUrl: 'slides.component.html', - styleUrls: ['slides.component.scss'], -}) -export class SlidesExample { - constructor() {} -} -``` - -Next, we need to import the stylesheet associated with the effect: +:::note +All methods and properties available on the Swiper instance can be found at https://swiperjs.com/swiper-api#methods-and-properties. +::: -```scss -// global.scss -@import '~swiper/scss/effect-fade'; -``` +## Effects -After that, we can activate it by setting the `effect` property on `swiper` to `"fade"`: +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: ```html - - - - Slide 1 - Slide 2 - Slide 3 - -``` - -```javascript -// slides.component.ts -import { Component } from '@angular/core'; -import SwiperCore, { EffectFade } from 'swiper'; -import { IonicSlides } from '@ionic/angular'; - -SwiperCore.use([EffectFade, IonicSlides]); - -@Component({ - selector: 'app-slides-example', - templateUrl: 'slides.component.html', - styleUrls: ['slides.component.scss'], -}) -export class SlidesExample { - constructor() {} -} + + ... + ``` :::note -For more information on effects in Swiper, please see https://swiperjs.com/angular#effects. +For more information on effects in Swiper, please see https://swiperjs.com/swiper-api#fade-effect. ::: ## 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 the Swiper Angular Introduction and then referencing the Swiper API docs. +Now that you have Swiper installed, there is a whole set of new Swiper features for you to enjoy. We recommend starting with the Swiper Element documentation and then referencing the Swiper API docs. ## FAQ @@ -442,4 +326,4 @@ Before opening an issue, please consider creating a post on the https://github.com/nolimits4web/swiper/issues -If you are running into problems with the `IonicSlides` module, new bugs should be filed on the Ionic Framework repo: https://github.com/ionic-team/ionic-framework/issues \ No newline at end of file +If you are running into problems with the `IonicSlides` module, new bugs should be filed on the Ionic Framework repo: https://github.com/ionic-team/ionic-framework/issues From 3bd427a55350a84e35c39257fe81648dbd73835a Mon Sep 17 00:00:00 2001 From: amandaesmith333 Date: Tue, 14 Mar 2023 14:51:02 -0500 Subject: [PATCH 2/3] split IonicSlides code into separate blocks --- docs/angular/slides.md | 6 +++++- versioned_docs/version-v6/angular/slides.md | 6 +++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/angular/slides.md b/docs/angular/slides.md index 02e900c7a18..b13e15440d0 100644 --- a/docs/angular/slides.md +++ b/docs/angular/slides.md @@ -138,6 +138,7 @@ We can install the `IonicSlides` module by importing it from `@ionic/angular` an ```typescript // home.page.ts + import { IonicSlides } from '@ionic/angular'; @Component({ @@ -146,8 +147,11 @@ import { IonicSlides } from '@ionic/angular'; export class HomePage { swiperModules = [IonicSlides]; } +``` + +```html + -// home.page.html ... diff --git a/versioned_docs/version-v6/angular/slides.md b/versioned_docs/version-v6/angular/slides.md index ef1c951984f..4ef0ff0afd3 100644 --- a/versioned_docs/version-v6/angular/slides.md +++ b/versioned_docs/version-v6/angular/slides.md @@ -136,6 +136,7 @@ We can install the `IonicSlides` module by importing it from `@ionic/angular` an ```typescript // home.page.ts + import { IonicSlides } from '@ionic/angular'; @Component({ @@ -144,8 +145,11 @@ import { IonicSlides } from '@ionic/angular'; export class HomePage { swiperModules = [IonicSlides]; } +``` + +```html + -// home.page.html ... From f5a6dcc55307c6119670b2a0aac42e457b298a52 Mon Sep 17 00:00:00 2001 From: Amanda Johnston <90629384+amandaejohnston@users.noreply.github.com> Date: Wed, 15 Mar 2023 09:44:49 -0500 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Liam DeBeasi --- docs/angular/slides.md | 2 +- versioned_docs/version-v6/angular/slides.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/angular/slides.md b/docs/angular/slides.md index b13e15440d0..eb2586540a8 100644 --- a/docs/angular/slides.md +++ b/docs/angular/slides.md @@ -56,7 +56,7 @@ register(); From there, we just have to replace `ion-slides` elements with `swiper-container` and `ion-slide` elements with `swiper-slide`. Note that these custom elements do not need to be imported, as calling `register` tells Angular about them on its own. -```typescript +```html Slide 1 Slide 2 diff --git a/versioned_docs/version-v6/angular/slides.md b/versioned_docs/version-v6/angular/slides.md index 4ef0ff0afd3..90310419958 100644 --- a/versioned_docs/version-v6/angular/slides.md +++ b/versioned_docs/version-v6/angular/slides.md @@ -54,7 +54,7 @@ register(); From there, we just have to replace `ion-slides` elements with `swiper-container` and `ion-slide` elements with `swiper-slide`. Note that these custom elements do not need to be imported, as calling `register` tells Angular about them on its own. -```typescript +```html Slide 1 Slide 2