astro-swiper

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

Install

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

Read the full doc on Github

Swiper options documentation can be found on swiperjs.com

Examples

Autoplay Example

Autoplay example: slider of 3 images, looping.

Full code

Code Snippet

---
import { Swiper, SwiperWrapper, SwiperSlide } from "astro-swiper";
---
<Swiper
options={{    // check options at https://swiperjs.com/swiper-api
  autoplay: {
    delay: 700,
    disableOnInteraction: false,
    waitForTransition: false,
  },
  loop: true,
}}>
<SwiperWrapper>
  <SwiperSlide> <img src=... /> </SwiperSlide>
  <SwiperSlide> <img src=... /> </SwiperSlide>
  <SwiperSlide> <img src=... /> </SwiperSlide>
</SwiperWrapper>
</Swiper>

Navigation Example

Navigation example: slider of 3 images, with arrow or swiping to navigate from a slide to another one.

Note that if ones does not want to use the default swiper class swiper-button-prev and swiper-button-next to use its own css, it is possible to use

<SwiperButtonPrev addDefaultClass={false} class='my-swiper-button-prev'/>

Full code

Code Snippet

---
...
import { SwiperButtonPrev, SwiperButtonNext } from "astro-swiper";
import type { AstroSwiperType } from "astro-swiper";

const astroSwiperOptions: AstroSwiperType = {
options: {
  loop: true,
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
},
};
---
<Swiper>
<SwiperWrapper>
  <SwiperSlide> <img src=... /> </SwiperSlide>
  <SwiperSlide> <img src=... /> </SwiperSlide>
  <SwiperSlide> <img src=... /> </SwiperSlide>
</SwiperWrapper>

<SwiperButtonPrev />
<SwiperButtonNext />
</Swiper>

Pagination Example

Pagination example: slider of 3 images, with autoplay and pagination: 3 dots indicates which slide is displayed.

Full code

Code Snippet

---
...
import { SwiperButtonPrev, SwiperButtonNext } from "astro-swiper";
...
---
<Swiper>
<SwiperWrapper>
  <SwiperSlide> <img src=... /> </SwiperSlide>
  <SwiperSlide> <img src=... /> </SwiperSlide>
  <SwiperSlide> <img src=... /> </SwiperSlide>
</SwiperWrapper>

<SwiperPagination />
</Swiper>

Thumbnail Example

Thumbnail example: a slider, with thumbnails at the bottom to see the progress.

The code is made of:

2 slides: 1 for the main slide, and one for the thumbnail
each slide have a uniqueClass defined
the main slider refers to the thumbnail one using linkToThumbUniqueClass being the uniqueClass of the thumbnail slide
the thumbnail slider has an option to set the number of thumbs to show

Full code

Code Snippet

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

<Swiper
uniqueClass="myswiper-main"
linkToThumbUniqueClass="myswiper-thumbnail"
options={{ ... }}>
<SwiperWrapper>
  <SwiperSlide> ... </SwiperSlide>
  <SwiperSlide> ... </SwiperSlide>
  ...
</SwiperWrapper>
</Swiper>

<Swiper
uniqueClass="myswiper-thumbnail"
options={{
  slidesPerView: 4,
  freeMode: true,
  watchSlidesProgress: true,
  ...
}}>
<SwiperWrapper>
  <SwiperSlide> ... </SwiperSlide>
  <SwiperSlide> ... </SwiperSlide>
  ...
</SwiperWrapper>
</Swiper>

How others are using astro-swiper

Here is how others are using astro-swiper, as found 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	IntersectionObserverInit	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';

Swiperjs demo

Here is how swiperjs.com demos are implemented with astro-swiper:

astro-swiper

Install

Examples

<Swiper/>

<SwiperWrapper/>

<SwiperSlide/>

<SwiperPagination/>

<SwiperButtonPrev/> and <SwiperButtonNext/>

<SwiperScrollbar/>

<SwiperLazyPreloader/>

getSwiperFromUniqueSelector()

Swiper types

Slide 4

Help needed?

Support us

`<Swiper/>`

`<SwiperWrapper/>`

`<SwiperSlide/>`

`<SwiperPagination/>`

`<SwiperButtonPrev/>` and `<SwiperButtonNext/>`

`<SwiperScrollbar/>`

`<SwiperLazyPreloader/>`

`getSwiperFromUniqueSelector()`