astro-swiper 2.2.2 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-swiper",
-  "version": "2.2.2",
+  "version": "2.4.0",
   "description": "Astro component for swiper, dedicated to slider / carousel / photo swiper / slide, including thumbnails",
   "type": "module",
   "main": "index.js",
@@ -35,9 +35,9 @@
   },
   "packageManager": "pnpm@10.30.3",
   "devDependencies": {
-    "@biomejs/biome": "^2.4.4",
-    "@types/node": "^24.11.0",
-    "astro": "^5.18.0",
+    "@biomejs/biome": "^2.4.9",
+    "@types/node": "^24.12.0",
+    "astro": "^5.18.1",
     "prettier": "^3.8.1",
     "prettier-plugin-astro": "^0.14.1",
     "typescript": "^5.9.3"
@@ -58,6 +58,6 @@
     "thumbnail"
   ],
   "dependencies": {
-    "swiper": "^12.1.2"
+    "swiper": "^12.1.3"
   }
 }

package/src/components/Swiper.astro

@@ -43,13 +43,13 @@ const {
 
 <script>
   import Swiper from 'swiper/bundle';
-  import type { SwiperOptions } from 'swiper/types';
+  import type { AstroSwiperOptions } from 'astro-swiper';
 
   /** contains the swiper json object once created, for each uniqueClass */
   const _useSwiper: { [uniqueClass: string]: Swiper } = {};
 
   /** contains the option used when creating the swiper object for each uniqueClass */
-  const _useOptions: { [uniqueClass: string]: SwiperOptions } = {};
+  const _useOptions: { [uniqueClass: string]: AstroSwiperOptions } = {};
 
   /** contains all the uniqueClass that have their swiper object delayed because the
    * related thumbnail swiper is not created yet
@@ -57,6 +57,97 @@ const {
    */
   const _useDelaySwiper: { [uniqueClass: string]: string } = {};
 
+  // Init swipers that have delayed initialization because the thumbnail swiper is not created yet
+  // If this is now the case, then it is intialized, as well as its observer if needed
+  function _initDelayedSwipers() {
+    Object.keys(_useDelaySwiper).forEach((delayedClass) => {
+      // swiper of uniqueClass "delayedClass" is delayed because it needs the swiper of uniqueClass
+      // "delayedThumbClass" to be created first
+      const delayedThumbClass = _useDelaySwiper[delayedClass];
+      if (_useSwiper[delayedThumbClass]) {
+        // the thumbnail swiper is created, we can create the swiper
+        delete _useDelaySwiper[delayedClass]; // remove it from the delayed list
+        const delayedOptions = _useOptions[delayedClass];
+        delayedOptions.thumbs = {
+          swiper: _useSwiper[delayedThumbClass], // add the thumbnail swiper link to the options
+          ...delayedOptions.thumbs,
+        };
+
+        _createSwiperAndObserver(
+          delayedClass,
+          delayedOptions,
+          document.querySelector(`.${delayedClass}`) as AstroSwiper,
+        );
+        _useOptions[delayedClass] = delayedOptions; // update the options with the thumbnail link
+      }
+    });
+  }
+
+  // initialize the swiper instance
+  // the autoplay may be stopped manually if it should be started by the observer
+  function _initSwiper(uniqueClass: string, options: AstroSwiperOptions, element: AstroSwiper) {
+    const swiper = new Swiper(`.${uniqueClass}`, options);
+    _useSwiper[uniqueClass] = swiper;
+    element.astroSwiper = swiper;
+
+    // stop the autoplay if it will be started by the observer
+    if (options.astro?.intersectionObserver?.controlAutoplay && options.autoplay) {
+      swiper.autoplay.stop();
+    }
+
+    _initDelayedSwipers();
+    return swiper;
+  }
+
+  function _createObserver(uniqueClass: string, options: AstroSwiperOptions, element: AstroSwiper) {
+    const observerOptions = options.astro?.intersectionObserver || {};
+    const observer = new IntersectionObserver((entries) => {
+      if (entries[0].isIntersecting) {
+        if (observerOptions?.initSwiper && !element.astroSwiper) {
+          _initSwiper(uniqueClass, options, element);
+          if (observerOptions?.disconnectOnInit) {
+            observer.disconnect();
+          }
+        }
+      }
+
+      const swiper = element?.astroSwiper;
+      if (!swiper) {
+        return;
+      }
+
+      if (observerOptions?.controlAutoplay && options.autoplay) {
+        if (entries[0].isIntersecting) {
+          swiper.autoplay.start();
+        } else {
+          swiper.autoplay.stop();
+        }
+      }
+    }, observerOptions.options);
+
+    observer.observe(element);
+    window.addEventListener('unload', observer.disconnect);
+  }
+
+  // create the swiper and the observer
+  // - init the swiper if it should not be done by the observer
+  // - create the observer if required
+  function _createSwiperAndObserver(
+    uniqueClass: string,
+    options: AstroSwiperOptions,
+    element: AstroSwiper,
+  ) {
+    if (!options.astro?.intersectionObserver?.initSwiper) {
+      // create the swiper immediatly
+      _initSwiper(uniqueClass, options, element);
+    }
+
+    // create the observer. It may init the swiper
+    if (options.astro?.intersectionObserver) {
+      _createObserver(uniqueClass, options, element);
+    }
+  }
+
   class AstroSwiper extends HTMLElement {
     /** pointer to the swiper structure that was created using "new",
      *  even when not initialized */
@@ -67,50 +158,26 @@ const {
       this.astroSwiper = undefined;
 
       // Read the message from the data attribute.
-      const options = JSON.parse(this.dataset.options || '{}');
+      const options: AstroSwiperOptions = JSON.parse(this.dataset.options || '{}');
       // to have more than 1 swiper in a single page
       const uniqueClass = this.dataset.uniqueclass || '';
       const linkToThumbUniqueClass = this.dataset.linktothumbuniqueclass || '';
 
-      if (linkToThumbUniqueClass === '') {
-        // no thumbnail link - the swiper can be created immediatly
-        const swiper = new Swiper(`.${uniqueClass}`, options);
-        _useSwiper[uniqueClass] = swiper;
-        this.astroSwiper = swiper;
-      } else {
-        // a thumbnail link is provided
-        // if the thumbnail swiper is already created, the main slider can be created also
-        // otherwise, it will be added in the delayed swiper list
-        if (_useSwiper[linkToThumbUniqueClass] !== undefined) {
+      // no thumbnail link, or link to thumbnail swiper already created,
+      // the swiper can be created or not immediatly depending on the observer option
+      if (!linkToThumbUniqueClass || _useSwiper[linkToThumbUniqueClass]) {
+        if (linkToThumbUniqueClass) {
           options.thumbs = { swiper: _useSwiper[linkToThumbUniqueClass], ...options.thumbs };
-          const swiper = new Swiper(`.${uniqueClass}`, options);
-          _useSwiper[uniqueClass] = swiper;
-          this.astroSwiper = swiper;
-        } else {
-          // cannot create the swiper as the thumbnail swiper not created yet
-          // will be done later
-          _useDelaySwiper[uniqueClass] = linkToThumbUniqueClass;
         }
+        // create the swiper and the observer if needed
+        _createSwiperAndObserver(uniqueClass, options, this);
+      } else {
+        // cannot create the swiper as the thumbnail swiper not created yet
+        // is delayed until the thumbnail swiper is initialized.
+        _useDelaySwiper[uniqueClass] = linkToThumbUniqueClass;
       }
 
       _useOptions[uniqueClass] = options;
-
-      // look if any delayed swiper can be created, that is its related thumbnail swiper is now created
-      Object.keys(_useDelaySwiper).forEach((delayedClass) => {
-        const delayedThumbClass = _useDelaySwiper[delayedClass];
-        if (_useSwiper[delayedThumbClass] !== undefined) {
-          const delayedOptions = _useOptions[delayedClass];
-          delayedOptions.thumbs = {
-            swiper: _useSwiper[delayedThumbClass],
-            ...delayedOptions.thumbs,
-          };
-          const swiper = new Swiper(`.${delayedClass}`, delayedOptions);
-          _useSwiper[delayedClass] = swiper;
-          (document.querySelector(`.${delayedClass}`) as AstroSwiper).astroSwiper = swiper;
-          _useOptions[delayedClass] = delayedOptions;
-          delete _useDelaySwiper[delayedClass];
-        }
-      });
     }
   }
 

package/src/components/SwiperLazyPreloader.astro

@@ -0,0 +1,19 @@
+---
+// Copyright (c) Pascal Brand
+// MIT License
+
+import 'swiper/css/bundle';
+
+import type { HTMLAttributes } from 'astro/types';
+
+interface Props extends HTMLAttributes<'div'> {
+  /** add the default swiper class, true by default */
+  addDefaultClass?: boolean;
+}
+
+const { class: className = null, addDefaultClass = true, ...props } = Astro.props;
+---
+
+<div class:list={[addDefaultClass ? 'swiper-lazy-preloader' : null, className]} {...props}>
+  <slot />
+</div>

package/src/index.ts

@@ -4,6 +4,32 @@
 import type { Swiper, SwiperOptions } from 'swiper/types';
 import type { HTMLAttributes } from 'astro/types';
 
+/** Swiper options for the Astro component.
+ * Basically the same as the original SwiperOptions, but extended
+ * with new capabilities
+ */
+export interface AstroSwiperOptions extends SwiperOptions {
+  /** options specific to astro-swiper component */
+  astro?: {
+    /** intersection observer options: an observer can be added to control the swiper when it appears / disappears in the screen.
+     * The observer is created using IntersectionObserver
+     * The behavior of the observer is controlled by the following properties
+     * When observer is not provided, no observer is created.
+     */
+    intersectionObserver?: {
+      /** true to initialize the swiper when the element appears in the screen */
+      initSwiper?: boolean;
+      /** true to disconnect the observer once the swiper is initialized */
+      disconnectOnInit?: boolean;
+      /** true to start and stop the autoplay when the swiper appears and disappears from the screen, respectively. */
+      controlAutoplay?: boolean;
+      /** options for the IntersectionObserver */
+      options?: IntersectionObserverInit;
+    };
+    /** TODO: uniqueClass and linkToThumbUniqueClass may be part of it */
+  };
+}
+
 /** properties passed to the <Swiper> component
  * It extends a div (that is may have class, style,...), plus other attributes
  * Note that all other components (<SwiperSlide>, <SwiperButtonNext>...) extends a div only
@@ -12,7 +38,7 @@ export interface AstroSwiperType extends HTMLAttributes<'div'> {
   /** swiper options, to set autoplay, navigation, thumbnails,...
    * check fullset of options: https://swiperjs.com/swiper-api#parameters
    */
-  options?: SwiperOptions;
+  options?: AstroSwiperOptions;
 
   /** unique class to be able to retrieve the swiper instance, if required
    * Mandatory on thumbnail for example
@@ -43,6 +69,7 @@ export interface AstroSwiperType extends HTMLAttributes<'div'> {
 export { default as Swiper } from './components/Swiper.astro';
 export { default as SwiperButtonNext } from './components/SwiperButtonNext.astro';
 export { default as SwiperButtonPrev } from './components/SwiperButtonPrev.astro';
+export { default as SwiperLazyPreloader } from './components/SwiperLazyPreloader.astro';
 export { default as SwiperPagination } from './components/SwiperPagination.astro';
 export { default as SwiperScrollbar } from './components/SwiperScrollbar.astro';
 export { default as SwiperSlide } from './components/SwiperSlide.astro';