astro-swiper 2.1.0 → 2.2.1

package/README.md

@@ -1,66 +1,46 @@
-<div align="center" style="background-color: black; padding: 16px;">
-  <a href="https://swiperjs.com" target="_blank"><img width="70" src="images/swiper-logo.svg"></a>
-  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
-  <a href="https://astro.build/" target="_blank"><img height="70" src="images/astro-logo.png"></a>
-
+<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).
+> Use for slides, carousel, photo swiper.
 
-  Astro Swiper is the native Astro component for
-  <a href="https://github.com/nolimits4web/swiper">Swiper</a>,
-  dedicated to slides / carousel / photo swiper.
-
-  # [Demo](https://pascal-brand38.github.io/astro-dev/packages/astro-swiper)
+  <img src="images/astro-swiper.gif" />
 
-  <a href="https://pascal-brand38.github.io/astro-dev/packages/astro-swiper" target="_blank">
-    <img src="images/astro-swiper.gif">
-  </a>
+## [Check demo](https://pascal-brand38.github.io/astro-dev/packages/astro-swiper)
 
 </div>
 
-<br>
-<br>
-
-# Help needed
-
-Do you need help to integrate ```astro-swiper``` in your
-astro template / component? 2 ways to ask:
-* mention me with ```@pascal-brand38``` in an issue on your own github repo
-* or [fill a github issue](https://github.com/pascal-brand38/astro-swiper/issues/new?template=help-needed.md)
-  in ```astro-swiper``` github
-
-I'll be happy to help!
-
-
-<br>
+## Installation
 
-# Installation
-Get the latest version from NPM:
+```bash
+npm install astro-swiper
+pnpm add astro-swiper
+bun install astro-swiper
 ```
-$ npm install astro-swiper
-```
-
-# Usage
 
-## First Example
+## Usage
 
-Here is the astro code of a loop carousel, of 3 pictures, with 1 second interval:
+Carousel with loop, 3 pictures, 1 second interval:
 
 ```jsx
 ---
 import { Swiper, SwiperWrapper, SwiperSlide } from "astro-swiper";
 ---
+
 <Swiper
-  options={{    // check options at https://swiperjs.com/swiper-api
+// check options at https://swiperjs.com/swiper-api
+  options={{
+    loop: true,
     autoplay: {
       delay: 700,
       disableOnInteraction: false,
-      waitForTransition: false,
-    },
-    loop: true,
+      waitForTransition: false
+    }
   }}>
   <SwiperWrapper>
-    <!-- Slides -->
     <SwiperSlide>
       <img src="https://picsum.photos/455/256?nb=1" alt="" />
     </SwiperSlide>
@@ -85,13 +65,50 @@ import { Swiper, SwiperWrapper, SwiperSlide } from "astro-swiper";
 </style>
 ```
 
-## Complex Examples
-
-Please check the [online doc](https://pascal-brand38.github.io/astro-dev/packages/astro-swiper) for a fullset of examples, including navigation and thumbnails.
-
-Full code is provided.
+## Examples
+
+Check the [online doc](https://pascal-brand38.github.io/astro-dev/packages/astro-swiper) for a fullset of examples, including navigation and thumbnails. Full code is provided.
+
+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
+- 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/),
+  [signin](https://pinwheel-astro.vercel.app/signin),
+  [password reset](https://pinwheel-astro.vercel.app/password-reset) and
+  [signup](https://pinwheel-astro.vercel.app/signup) pages. Pagination and
+  breakpoints are used.
+- the well-known astro template [hello-astro](https://github.com/hellotham/hello-astro)
+  uses swiper in the [carousel page](https://hellotham.github.io/hello-astro/carousel/)
+  as well as in [blog article](https://hellotham.github.io/hello-astro/blog/2022-08-19-sample-carousel/).
+  It makes use of navigation arrow, pagination and autoplay.
+- [bigspring-light-astro](https://github.com/themefisher/bigspring-light-astro) astro theme is
+  also using `astro-swiper` in several places in the
+  [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/)
+- [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
+- ... 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
+
+## Help needed?
+
+**Do you need help to integrate `astro-swiper` in your astro template / component?**
+I'll be happy to help!
 
+- mention me with `@pascal-brand38` in an issue on your own github repo
+- or [fill a GitHub issue](https://github.com/pascal-brand38/astro-swiper/issues/new?template=help-needed.md)
+  in `astro-swiper` github
 
-# Support astro-swiper
+### Support us
 
-Please [star the project](https://github.com/pascal-brand38/astro-swiper) if you like it!
+**Let's star the project as you like it.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-swiper",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Astro component for swiper, dedicated to slider / carousel / photo swiper / slide, including thumbnails",
   "main": "index.js",
   "scripts": {
@@ -17,19 +17,24 @@
   "bugs": {
     "url": "https://github.com/pascal-brand38/astro-swiper/issues"
   },
-  "homepage": "https://pascal-brand38.github.io/astro-dev/packages/astro-swiper/",
+  "homepage": "https://github.com/pascal-brand38/astro-swiper",
   "exports": "./index.ts",
   "files": [
     "index.ts",
     "src/**"
   ],
+  "engines": {
+    "pnpm": ">=10.30.3",
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@10.30.3",
   "devDependencies": {
-    "@biomejs/biome": "^2.3.14",
-    "@types/node": "^24.0.0",
-    "astro": "^5.9.2",
+    "@biomejs/biome": "^2.4.4",
+    "@types/node": "^24.11.0",
+    "astro": "^5.18.0",
     "prettier": "^3.8.1",
     "prettier-plugin-astro": "^0.14.1",
-    "typescript": "^5.8.3"
+    "typescript": "^5.9.3"
   },
   "keywords": [
     "swiper",
@@ -47,6 +52,6 @@
     "thumbnail"
   ],
   "dependencies": {
-    "swiper": "^12.0.0"
+    "swiper": "^12.1.2"
   }
 }

package/src/components/Swiper.astro

@@ -18,20 +18,19 @@ const {
 } = Astro.props;
 ---
 
-<!-- Slider main container -->
-{
+<!-- Slider main container -->{
   useCustomElement ? (
     <astro-swiper
       data-options={JSON.stringify(options)}
       data-linktothumbuniqueclass={linkToThumbUniqueClass}
       data-uniqueclass={uniqueClass}
-      class:list={[addDefaultClass ? 'swiper' : '', uniqueClass, className]}
+      class:list={[addDefaultClass ? 'swiper' : null, uniqueClass, className]}
       {...props}
     >
       <slot />
     </astro-swiper>
   ) : (
-    <div class:list={[addDefaultClass ? 'swiper' : '', uniqueClass, className]} {...props} >
+    <div class:list={[addDefaultClass ? 'swiper' : null, uniqueClass, className]} {...props}>
       <astro-swiper
         data-options={JSON.stringify(options)}
         data-linktothumbuniqueclass={linkToThumbUniqueClass}
@@ -69,7 +68,8 @@ const {
 
       // Read the message from the data attribute.
       const options = JSON.parse(this.dataset.options || '{}');
-      const uniqueClass = this.dataset.uniqueclass || ''; // to have more than 1 swiper in a single page
+      // to have more than 1 swiper in a single page
+      const uniqueClass = this.dataset.uniqueclass || '';
       const linkToThumbUniqueClass = this.dataset.linktothumbuniqueclass || '';
 
       if (linkToThumbUniqueClass === '') {

package/src/components/SwiperButtonNext.astro

@@ -11,9 +11,9 @@ interface Props extends HTMLAttributes<'div'> {
   addDefaultClass?: boolean;
 }
 
-const { class: className = '', addDefaultClass = true, ...props } = Astro.props;
+const { class: className = null, addDefaultClass = true, ...props } = Astro.props;
 ---
 
-<div class:list={[addDefaultClass ? 'swiper-button-next' : '', className]} {...props}>
+<div class:list={[addDefaultClass ? 'swiper-button-next' : null, className]} {...props}>
   <slot />
 </div>

package/src/components/SwiperButtonPrev.astro

@@ -11,9 +11,9 @@ interface Props extends HTMLAttributes<'div'> {
   addDefaultClass?: boolean;
 }
 
-const { class: className = '', addDefaultClass = true, ...props } = Astro.props;
+const { class: className = null, addDefaultClass = true, ...props } = Astro.props;
 ---
 
-<div class:list={[addDefaultClass ? 'swiper-button-prev' : '', className]} {...props}>
+<div class:list={[addDefaultClass ? 'swiper-button-prev' : null, className]} {...props}>
   <slot />
 </div>

package/src/components/SwiperPagination.astro

@@ -11,9 +11,9 @@ interface Props extends HTMLAttributes<'div'> {
   addDefaultClass?: boolean;
 }
 
-const { class: className = '', addDefaultClass = true, ...props } = Astro.props;
+const { class: className = null, addDefaultClass = true, ...props } = Astro.props;
 ---
 
-<div class:list={[addDefaultClass ? 'swiper-pagination' : '', className]} {...props}>
+<div class:list={[addDefaultClass ? 'swiper-pagination' : null, className]} {...props}>
   <slot />
 </div>

package/src/components/SwiperScrollbar.astro

@@ -11,9 +11,9 @@ interface Props extends HTMLAttributes<'div'> {
   addDefaultClass?: boolean;
 }
 
-const { class: className = '', addDefaultClass = true, ...props } = Astro.props;
+const { class: className = null, addDefaultClass = true, ...props } = Astro.props;
 ---
 
-<div class:list={[addDefaultClass ? 'swiper-scrollbar' : '', className]} {...props}>
+<div class:list={[addDefaultClass ? 'swiper-scrollbar' : null, className]} {...props}>
   <slot />
 </div>

package/src/components/SwiperSlide.astro

@@ -10,7 +10,7 @@ interface Props extends HTMLAttributes<'div'> {
   addDefaultClass?: boolean;
 }
 
-const { class: className = '', addDefaultClass = true, ...props } = Astro.props;
+const { class: className = null, addDefaultClass = true, ...props } = Astro.props;
 ---
 
 <div class:list={[addDefaultClass ? 'swiper-slide' : null, className]} {...props}>

package/src/components/SwiperWrapper.astro

@@ -11,9 +11,9 @@ interface Props extends HTMLAttributes<'div'> {
   addDefaultClass?: boolean;
 }
 
-const { class: className = '', addDefaultClass = true, ...props } = Astro.props;
+const { class: className = null, addDefaultClass = true, ...props } = Astro.props;
 ---
 
-<div class:list={[addDefaultClass ? 'swiper-wrapper' : '', className]} {...props}>
+<div class:list={[addDefaultClass ? 'swiper-wrapper' : null, className]} {...props}>
   <slot />
 </div>

package/src/index.ts

@@ -39,7 +39,7 @@ export interface AstroSwiperType extends HTMLAttributes<'div'> {
   useCustomElement?: boolean;
 }
 
-/** astro components exported, used to create a swiper */
+/** Astro components exports, used to create a swiper */
 export { default as Swiper } from './components/Swiper.astro';
 export { default as SwiperButtonNext } from './components/SwiperButtonNext.astro';
 export { default as SwiperButtonPrev } from './components/SwiperButtonPrev.astro';
@@ -48,44 +48,46 @@ export { default as SwiperScrollbar } from './components/SwiperScrollbar.astro';
 export { default as SwiperSlide } from './components/SwiperSlide.astro';
 export { default as SwiperWrapper } from './components/SwiperWrapper.astro';
 
+/** pointer to the swiper structure that was created using "new", even when not initialized */
 declare class AstroSwiper extends HTMLElement {
-  /** pointer to the swiper structure that was created using "new",
-   *  even when not initialized */
   astroSwiper: Swiper | undefined;
 }
 
+// !TODO Deprecate fully in next major version
 /** @deprecated: use getSwiperFromUniqueSelector() instead */
 export function getSwiperFromUniqueClass(uniqueClass: string): Swiper | undefined {
   return getSwiperFromUniqueSelector(`.${uniqueClass}`);
 }
 
-/** Retrieve the swiper instance from the unique selector provided
- * when creating the swiper
+/** Retrieve the swiper instance from the unique selector provided when creating the swiper
  * @param uniqueSelector the unique selector provided when creating the swiper,
  * @example const swiper = getSwiperFromUniqueSelector('.my-unique-class')
  *          const swiper = getSwiperFromUniqueSelector('#my-unique-id')
  */
 export function getSwiperFromUniqueSelector(uniqueSelector: string): Swiper | undefined {
-  let swiperEl: AstroSwiper = document.querySelector(uniqueSelector) as AstroSwiper;
-  if (!swiperEl) {
-    console.warn(`astro-swiper: no element found with unique selector "${uniqueSelector}"`);
-    return undefined;
-  }
-  if (swiperEl.astroSwiper) {
-    // this is the custom element that contains the swiper instance, return it
-    return swiperEl.astroSwiper;
+  if (!/^[.#]/.test(uniqueSelector)) {
+    console.warn("Used selector doesn't contain class or ID selector sign");
   }
 
-  // this a div, with 1st child being the custom element that contains the swiper instance
-  swiperEl = swiperEl.firstElementChild as AstroSwiper;
-  if (!swiperEl) {
-    console.warn(`astro-swiper: no element found with unique selector "${uniqueSelector}"`);
+  const element = document.querySelector(uniqueSelector);
+
+  if (!element) {
+    console.warn(`astro-swiper: no element found with selector "${uniqueSelector}"`);
     return undefined;
   }
-  if (swiperEl.astroSwiper) {
-    return swiperEl.astroSwiper;
-  }
 
-  console.warn(`astro-swiper: no element found with unique selector "${uniqueSelector}"`);
+  // Check if element is the customElement with astroSwiper property
+  const customElement = element as AstroSwiper;
+  if (customElement.astroSwiper) return customElement.astroSwiper;
+
+  // Check if element is a <div/> wrapper with customElement child
+  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.`,
+  );
+
   return undefined;
 }