astro-swiper 2.3.0 → 2.5.0

package/README.md

@@ -1,7 +1,7 @@
 <div align="center" style="background-color: dark-grey; padding: 1rem;">
   <a href="https://swiperjs.com" target="_blank"><img width="70" width="auto" src="images/swiper-logo.svg"></a>
   <a href="https://astro.build/" target="_blank"><img height="68" width="auto" src="images/astro-logo.svg"></a>
-  
+
   # Astro Swiper
 
 > Astro Swiper - native component for [Swiper](https://github.com/nolimits4web/swiper).
@@ -74,7 +74,7 @@ You can also look at how others are using `astro-swiper` in public github repo:
 - the famous astro template [astroplate](https://github.com/zeon-studio/astroplate) in the
   [testominial section](https://zeon.studio/preview?project=astroplate)
   (cf. **_What Users Are Saying About Astroplate_**):
-  autoplay, pagination and breakpoints are used
+  autoplay, pagination and breakpoints are used.
 - the popular astro template [pinwheel-astro](https://github.com/themefisher/pinwheel-astro)
   is using `astro-swiper` in several places:
   [testimonial section](https://pinwheel-astro.vercel.app/),
@@ -91,14 +91,18 @@ You can also look at how others are using `astro-swiper` in public github repo:
   [main page](https://tf-bigspring-light-astro.vercel.app/) with customized pagination.
 - [Women Techmakers organized by GDG Madrid](https://github.com/wtmgdgmadrid/wtmgdgmadrid.github.io)
   is using pagination and autoplay at different places in their
-  [page](http://wtmgdgmadrid.github.io/)
+  [page](http://wtmgdgmadrid.github.io/).
 - [kando-menu](https://github.com/make-42/kando-menu.github.io) is using `astro-swiper`
-  with pagination, card effect, and coverflow effect as displayed in [kando.menu](https://kando.menu/)
-- [astroimagej](https://github.com/AstroImageJ/astroimagej) is using pagination with progress bar
+  with pagination, card effect, and coverflow effect as displayed in [kando.menu](https://kando.menu/).
+- [astroimagej](https://github.com/AstroImageJ/astroimagej) is using pagination with progress bar.
+- [rustdesk.com](https://github.com/rustdesk/doc.rustdesk.com) makes use of `<SwiperLazyPreloader/>`
+  to add a preloader element.
 - ... and many others such as
   [Cinerama](https://github.com/RaiderMr3003/Cinerama) and
   [pfm-landing-page](https://github.com/RichardAgain/pfm-landing-page)
-  using `astro-swiper` in the hero section
+  using `astro-swiper` in the hero section,
+  [folex-lite-astro](https://github.com/getastrothemes/folex-lite-astro)
+  using it in the portfolio page,...
 
 ## Help needed?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-swiper",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Astro component for swiper, dedicated to slider / carousel / photo swiper / slide, including thumbnails",
   "type": "module",
   "main": "index.js",
@@ -18,7 +18,7 @@
   "bugs": {
     "url": "https://github.com/pascal-brand38/astro-swiper/issues"
   },
-  "homepage": "https://github.com/pascal-brand38/astro-swiper",
+  "homepage": "https://pascal-brand38.github.io/astro-dev/packages/astro-swiper/",
   "exports": {
     ".": {
       "types": "./index.ts",
@@ -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

@@ -9,20 +9,40 @@ type Props = AstroSwiperType;
 
 const {
   options = {},
-  uniqueClass = `astro-swiper-${Math.random().toString(36).slice(2, 11)}`,
+  uniqueClass: removedUniqueClass, // remove it once deprecated uniqueClass prop is removed
   class: className = null,
-  linkToThumbUniqueClass = null,
+  linkToThumbUniqueClass: removedLinkToThumbUniqueClass, // remove it once deprecated uniqueClass prop is removed
   addDefaultClass = true,
-  useCustomElement = true,
   ...props
 } = Astro.props;
+
+// check for deprecated useCustomElement prop and set the options.astro.useCustomElement
+// option accordingly if not set, to keep legacy
+if (options?.astro?.useCustomElement === undefined && Astro.props.useCustomElement === false) {
+  if (!options.astro) {
+    options.astro = {};
+  }
+  options.astro.useCustomElement = false;
+}
+
+// once Astro.props.uniqueClass is removed, uniqueClass can be directly set to the generated unique class name
+const uniqueClass =
+  Astro.props.uniqueClass || `astro-swiper-${Math.random().toString(36).slice(2, 11)}`;
+
+// check for deprecated useCustomElement prop and set the options.astro.useCustomElement
+// option accordingly if not set, to keep legacy
+if (options?.astro?.thumbSwiperUniqueSelector === undefined && Astro.props.linkToThumbUniqueClass) {
+  if (!options.astro) {
+    options.astro = {};
+  }
+  options.astro.thumbSwiperUniqueSelector = `.${Astro.props.linkToThumbUniqueClass}`;
+}
 ---
 
 <!-- Slider main container -->{
-  useCustomElement ? (
+  options?.astro?.useCustomElement !== false ? (
     <astro-swiper
       data-options={JSON.stringify(options)}
-      data-linktothumbuniqueclass={linkToThumbUniqueClass}
       data-uniqueclass={uniqueClass}
       class:list={[addDefaultClass ? 'swiper' : null, uniqueClass, className]}
       {...props}
@@ -31,11 +51,7 @@ const {
     </astro-swiper>
   ) : (
     <div class:list={[addDefaultClass ? 'swiper' : null, uniqueClass, className]} {...props}>
-      <astro-swiper
-        data-options={JSON.stringify(options)}
-        data-linktothumbuniqueclass={linkToThumbUniqueClass}
-        data-uniqueclass={uniqueClass}
-      />
+      <astro-swiper data-options={JSON.stringify(options)} data-uniqueclass={uniqueClass} />
       <slot />
     </div>
   )
@@ -43,47 +59,62 @@ const {
 
 <script>
   import Swiper from 'swiper/bundle';
-  import type { AstroSwiperOptions } from 'astro-swiper';
+  import { getSwiperFromUniqueSelector } from '../index';
+  import type { AstroSwiperOptions, selectorStringType } from '../index';
 
-  /** contains the swiper json object once created, for each uniqueClass */
-  const _useSwiper: { [uniqueClass: string]: Swiper } = {};
+  const getSwiperFromUniqueSelectorOptions = {
+    // to avoid warning when the swiper is not initialized yet, but will be in the future
+    // (for example when using thumbnails, the main swiper is created before the thumbnail
+    // swiper, so it is normal that it is not found at this moment)
+    mayBeUndefined: true,
+  };
 
-  /** contains the option used when creating the swiper object for each uniqueClass */
-  const _useOptions: { [uniqueClass: string]: AstroSwiperOptions } = {};
+  /** contains the option used when creating the swiper object for each uniqueSelector */
+  const _useOptions: { [uniqueSelector: string]: AstroSwiperOptions } = {};
 
-  /** contains all the uniqueClass that have their swiper object delayed because the
+  /** contains all the uniqueSelector that have their swiper object delayed because the
    * related thumbnail swiper is not created yet
-   * For each uniqueClass, is equal to the thumbnail slider uniqueClass
+   * For each uniqueSelector, is equal to the thumbnail slider uniqueSelector
    */
-  const _useDelaySwiper: { [uniqueClass: string]: string } = {};
+  const _useDelaySwiper: { [uniqueSelector: 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]) {
+    Object.keys(_useDelaySwiper).forEach((delayedSelector) => {
+      // swiper of uniqueSelector "delayedSelector" is delayed because it needs the swiper of uniqueSelector
+      // "delayedThumbSelector" to be created first
+      const delayedThumbSelector = _useDelaySwiper[delayedSelector];
+      const swiper = getSwiperFromUniqueSelector(
+        delayedThumbSelector,
+        getSwiperFromUniqueSelectorOptions,
+      );
+      if (swiper) {
         // the thumbnail swiper is created, we can create the swiper
-        delete _useDelaySwiper[delayedClass]; // remove it from the delayed list
-        const delayedOptions = _useOptions[delayedClass];
+        delete _useDelaySwiper[delayedSelector]; // remove it from the delayed list
+        const delayedOptions = _useOptions[delayedSelector];
         delayedOptions.thumbs = {
-          swiper: _useSwiper[delayedThumbClass],    // add the thumbnail swiper link to the options
+          swiper: swiper, // 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
+        _createSwiperAndObserver(
+          delayedSelector,
+          delayedOptions,
+          document.querySelector(delayedSelector) as AstroSwiper,
+        );
       }
     });
   }
 
   // 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;
+  function _initSwiper(
+    uniqueSelector: selectorStringType,
+    options: AstroSwiperOptions,
+    element: AstroSwiper,
+  ) {
+    const swiper = new Swiper(uniqueSelector, options);
     element.astroSwiper = swiper;
 
     // stop the autoplay if it will be started by the observer
@@ -95,51 +126,56 @@ const {
     return swiper;
   }
 
-  function _createObserver(uniqueClass: string, options: AstroSwiperOptions, element: AstroSwiper) {
+  function _createObserver(
+    uniqueSelector: selectorStringType,
+    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 observer = new IntersectionObserver((entries) => {
+      if (entries[0].isIntersecting) {
+        if (observerOptions?.initSwiper && !element.astroSwiper) {
+          _initSwiper(uniqueSelector, options, element);
+          if (observerOptions?.disconnectOnInit) {
+            observer.disconnect();
           }
         }
+      }
 
-        const swiper = element?.astroSwiper
-        if (!swiper) {
-          return;
-        }
+      const swiper = element?.astroSwiper;
+      if (!swiper) {
+        return;
+      }
 
-        if (observerOptions?.controlAutoplay && options.autoplay) {
-          if (entries[0].isIntersecting) {
-            swiper.autoplay.start();
-          } else {
-            swiper.autoplay.stop();
-          }
+      if (observerOptions?.controlAutoplay && options.autoplay) {
+        if (entries[0].isIntersecting) {
+          swiper.autoplay.start();
+        } else {
+          swiper.autoplay.stop();
         }
-      },
-      observerOptions.options,
-    );
+      }
+    }, observerOptions.options);
 
     observer.observe(element);
-    window.addEventListener("unload", observer.disconnect);
+    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)) {
+  function _createSwiperAndObserver(
+    uniqueSelector: selectorStringType,
+    options: AstroSwiperOptions,
+    element: AstroSwiper,
+  ) {
+    if (!options.astro?.intersectionObserver?.initSwiper) {
       // create the swiper immediatly
-      _initSwiper(uniqueClass, options, element);
+      _initSwiper(uniqueSelector, options, element);
     }
 
     // create the observer. It may init the swiper
     if (options.astro?.intersectionObserver) {
-      _createObserver(uniqueClass, options, element);
+      _createObserver(uniqueSelector, options, element);
     }
   }
 
@@ -155,24 +191,32 @@ const {
       // Read the message from the data attribute.
       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 || '';
+      const uniqueSelector: selectorStringType = `.${this.dataset.uniqueclass}`;
+      const thumbSwiperUniqueSelector = options.astro?.thumbSwiperUniqueSelector;
 
       // 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 };
+      if (
+        !thumbSwiperUniqueSelector ||
+        getSwiperFromUniqueSelector(thumbSwiperUniqueSelector, getSwiperFromUniqueSelectorOptions)
+      ) {
+        if (thumbSwiperUniqueSelector) {
+          options.thumbs = {
+            swiper: getSwiperFromUniqueSelector(
+              thumbSwiperUniqueSelector,
+              getSwiperFromUniqueSelectorOptions,
+            ),
+            ...options.thumbs,
+          };
         }
         // create the swiper and the observer if needed
-        _createSwiperAndObserver(uniqueClass, options, this);
+        _createSwiperAndObserver(uniqueSelector, 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;
+        _useDelaySwiper[uniqueSelector] = thumbSwiperUniqueSelector;
+        _useOptions[uniqueSelector] = options;
       }
-
-      _useOptions[uniqueClass] = options;
     }
   }
 

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,10 +4,13 @@
 import type { Swiper, SwiperOptions } from 'swiper/types';
 import type { HTMLAttributes } from 'astro/types';
 
+// type of a string that starts with a dot (class selector) or a hash (id selector), followed by any string
+export type selectorStringType = `.${string}` | `#${string}`;
+
 /** 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?: {
@@ -25,10 +28,26 @@ export interface AstroSwiperOptions extends SwiperOptions {
       controlAutoplay?: boolean;
       /** options for the IntersectionObserver */
       options?: IntersectionObserverInit;
-    }
-    /** TODO: uniqueClass and linkToThumbUniqueClass may be part of it */
-  }
-};
+    };
+
+    /** useCustomElement, if true, the component will be rendered as a custom element, otherwise as a div.
+     * This option is true by default to keep legacy.
+     * It is there to be as close as possible to the original swiper structure, that is a div with class "swiper"
+     * and not a custom element.
+     * It is also to avoid issues with some swiper modules that are looking for the "swiper" class on the parent
+     * element, and not on the custom element.
+     */
+    useCustomElement?: boolean;
+
+    /** unique selector of the thumbnail swiper to link with, when using the thumbs module.
+     * when a thumbnail swiper is build, this parameter is provided on the main slider
+     * (the one with big slides, not the one to track the progress) and equal
+     * the unique selector of the thumbnail swiper (the one to track the progress).
+     * It is used to link the main swiper with the thumbnail swiper when using the thumbs module.
+     */
+    thumbSwiperUniqueSelector?: selectorStringType;
+  };
+}
 
 /** properties passed to the <Swiper> component
  * It extends a div (that is may have class, style,...), plus other attributes
@@ -40,28 +59,17 @@ export interface AstroSwiperType extends HTMLAttributes<'div'> {
    */
   options?: AstroSwiperOptions;
 
-  /** unique class to be able to retrieve the swiper instance, if required
-   * Mandatory on thumbnail for example
-   * When undefined, an automatic unique class name is provided
-   */
+  /** add the default swiper class, true by default */
+  addDefaultClass?: boolean;
+
+  /** @deprecated is not really usefull anymore. If a specific unique class or id is needed,
+   * add it as an id or or a class directly */
   uniqueClass?: string;
 
-  /** a thumbnail slider is build, this parameter is provided on the main slider
-   * (the one with big slides, not the one to track the progress) and equal
-   * the unique class of the thumbnail slider
-   */
+  /** @deprecated use astro.options.astro.thumbsSwiperUniqueSelector instead */
   linkToThumbUniqueClass?: string;
 
-  /** add the default swiper class, true by default */
-  addDefaultClass?: boolean;
-
-  /** useCustomElement, if true, the component will be rendered as a custom element, otherwise as a div.
-   * This option is true by default to keep legacy.
-   * It is there to be as close as possible to the original swiper structure, that is a div with class "swiper"
-   * and not a custom element.
-   * It is also to avoid issues with some swiper modules that are looking for the "swiper" class on the parent
-   * element, and not on the custom element.
-   */
+  /** @deprecated use astro.useCustomElement instead */
   useCustomElement?: boolean;
 }
 
@@ -69,6 +77,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';
@@ -90,7 +99,10 @@ export function getSwiperFromUniqueClass(uniqueClass: string): Swiper | undefine
  * @example const swiper = getSwiperFromUniqueSelector('.my-unique-class')
  *          const swiper = getSwiperFromUniqueSelector('#my-unique-id')
  */
-export function getSwiperFromUniqueSelector(uniqueSelector: string): Swiper | undefined {
+export function getSwiperFromUniqueSelector(
+  uniqueSelector: selectorStringType,
+  options?: { mayBeUndefined?: boolean },
+): Swiper | undefined {
   if (!/^[.#]/.test(uniqueSelector)) {
     console.warn("Used selector doesn't contain class or ID selector sign");
   }
@@ -110,10 +122,16 @@ export function getSwiperFromUniqueSelector(uniqueSelector: string): Swiper | un
   const childElement = element.firstElementChild as AstroSwiper;
   if (childElement?.astroSwiper) return childElement.astroSwiper;
 
-  console.warn(
-    `astro-swiper: element found with selector "${uniqueSelector}" but no swiper instance found. ` +
-      `Expected either a custom element with astroSwiper property or a <div/> containing such an element.`,
-  );
+  if (!options?.mayBeUndefined) {
+    // set options.mayBeUndefined to true to avoid this warning when the swiper is not initialized yet,
+    // but will be in the future:
+    // for example when using thumbnails, the main swiper is created before the thumbnail swiper,
+    // so it is normal that it is not found at this moment)
+    console.warn(
+      `astro-swiper: element found with selector "${uniqueSelector}" but no swiper instance found. ` +
+        `Expected either a custom element with astroSwiper property or a <div/> containing such an element.`,
+    );
+  }
 
   return undefined;
 }