Astro Swiper

Astro Swiper - native component for Swiper. Use for slides, carousel, photo swiper.

Check demo

Installation

npm install astro-swiper
pnpm add astro-swiper
bun install astro-swiper

Usage

Carousel with loop, 3 pictures, 1 second interval:

---
import { Swiper, SwiperWrapper, SwiperSlide } from "astro-swiper";
---

<Swiper
  options={{
    loop: true,   // check options at https://swiperjs.com/swiper-api
    autoplay: {
      delay: 700,
      disableOnInteraction: false,
      waitForTransition: false
    }
  }}>
  <SwiperWrapper>
    <SwiperSlide>
      <img src="https://picsum.photos/455/256?nb=1" alt="" />
    </SwiperSlide>
    <SwiperSlide>
      <img src="https://picsum.photos/455/256?nb=2" alt="" />
    </SwiperSlide>
    <SwiperSlide>
      <img src="https://picsum.photos/455/256?nb=3" alt="" />
    </SwiperSlide>
  </SwiperWrapper>
</Swiper>

<style>
  .swiper {
    max-width: 455px;
    aspect-ratio: 16/9;
  }

  img {
    width: 100%;
  }
</style>

Examples

Check the online doc 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 in the testominial section (cf. What Users Are Saying About Astroplate): autoplay, pagination and breakpoints are used.
• the popular astro template pinwheel-astro is using astro-swiper in several places: testimonial section, signin, password reset and signup pages. Pagination and breakpoints are used.
• the well-known astro template hello-astro uses swiper in the carousel page as well as in blog article. It makes use of navigation arrow, pagination and autoplay.
• bigspring-light-astro astro theme is also using astro-swiper in several places in the main page with customized pagination.
• Women Techmakers organized by GDG Madrid is using pagination and autoplay at different places in their page.
• kando-menu is using astro-swiper with pagination, card effect, and coverflow effect as displayed in kando.menu.
• astroimagej is using pagination with progress bar.
• rustdesk.com makes use of <SwiperLazyPreloader/> to add a preloader element.
• ... and many others such as Cinerama and pfm-landing-page using astro-swiper in the hero section, folex-lite-astro using it in the portfolio page,...

API

<Swiper/>

Main Swiper element. Inherits all HTMLAttributes<'div'> (class...) attributes. | Name | Type | Default | Description | | ---- | -----|-------- | -----------| | options | SwiperOptions | Swiperjs default | cf. Swiperjs doc | | options.astro | Cf. below description | undefined | astro specific options | | addDefaultClass | Boolean | true | Add class .swiper when true |

options.astro is as follows: | Name | Type | Default | Description | | ---- | -----|-------- | -----------| | useCustomElement | boolean | true | when false, use a <div> to be as close as possible to swiperjs default. Use a custom element <astro-swiper> otherwise. | | thumbSwiperUniqueSelector | string starting with # or . | undefined | 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. | | intersectionObserver.initSwiper | boolean | false | true to initialize the swiper when the element appears in the screen | | intersectionObserver.disconnectOnInit | boolean | false | true to disconnect the observer once the swiper is initialized | | intersectionObserver.controlAutoplay | boolean | false | true to start and stop the autoplay when the swiper appears and disappears from the screen, respectively | | intersectionObserver.options | Intersection Observer Init options | undefined | cf. mdn docs |

<SwiperWrapper/>

Wrapper of all slides. Inherits all HTMLAttributes<'div'> (class...) attributes. | Name | Type | Default | Description | | ---- | -----|-------- | -----------| | addDefaultClass | Boolean | true | Add class .swiper-wrapper when true |

<SwiperSlide/>

A single slide. Inherits all HTMLAttributes<'div'> (class...) attributes. | Name | Type | Default | Description | | ---- | -----|-------- | -----------| | addDefaultClass | Boolean | true | Add class .swiper-slide when true |

<SwiperPagination/>

Pagination dots. Inherits all HTMLAttributes<'div'> (class...) attributes. | Name | Type | Default | Description | | ---- | -----|-------- | -----------| | addDefaultClass | Boolean | true | Add class .swiper-pagination when true |

<SwiperButtonPrev/> and <SwiperButtonNext/>

Navigation arrows. Inherits all HTMLAttributes<'div'> (class...) attributes. | Name | Type | Default | Description | | ---- | -----|-------- | -----------| | addDefaultClass | Boolean | true | Add class .swiper-button-prev or swiper-button-next when true |

<SwiperScrollbar/>

Scrollbar. Inherits all HTMLAttributes<'div'> (class...) attributes. | Name | Type | Default | Description | | ---- | -----|-------- | -----------| | addDefaultClass | Boolean | true | Add class .swiper-scrollbar when true |

<SwiperLazyPreloader/>

Slide lazy loader. To be used inside a <SwiperSlide/>. Inherits all HTMLAttributes<'div'> (class...) attributes. | Name | Type | Default | Description | | ---- | -----|-------- | -----------| | addDefaultClass | Boolean | true | Add class .swiper-lazy-preloader when true |

getSwiperFromUniqueSelector()

Function to be used in script part, to be able to retrieve the swiper instance given a unique selector (starting with a . or a #), once the load event is fired. This allows to use functions and events in swiper.

Here is a snipset of the Custom Pagination Demo:

<Swiper
  class="swiper-demo-pagination-custom"
  options={{
    ...
    init: false,  // init in the script part
  }}
>
  ...
  <SwiperPagination />
</Swiper>

<script>
  import type { PaginationOptions } from 'astro-swiper/swiper';
  import { getSwiperFromUniqueSelector } from 'astro-swiper'
  window.addEventListener('load', () => {
    const swiper = getSwiperFromUniqueSelector('.swiper-demo-pagination-custom');
    (swiper!.params.pagination as PaginationOptions)!.renderBullet = function (index: number, className: string) {
      return '<span class="' + className + '">' + (index + 1) + "</span>";
    }
    swiper!.init()
  })
</script>

Swiper types

Swiper types are available importing types from astro-swiper/swiper, such as

import type { PaginationOptions } from 'astro-swiper/swiper';

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 in astro-swiper github

Support us

Let's star the project as you like it.