Swiper React Components

Installation

Swiper React is available only via NPM as a part of the main Swiper library:

  npm i swiper@6

Usage

swiper/react exports 2 components: Swiper and SwiperSlide:

// Import Swiper React components
import { Swiper, SwiperSlide } from 'swiper/react';

// Import Swiper styles
import 'swiper/swiper.scss';

export default () => {
  return (
    <Swiper
      spaceBetween={50}
      slidesPerView={3}
      onSlideChange={() => console.log('slide change')}
      onSwiper={(swiper) => console.log(swiper)}
    >
      <SwiperSlide>Slide 1</SwiperSlide>
      <SwiperSlide>Slide 2</SwiperSlide>
      <SwiperSlide>Slide 3</SwiperSlide>
      <SwiperSlide>Slide 4</SwiperSlide>
      ...
    </Swiper>
  );
};

By default Swiper React uses core version of Swiper (without any additional modules). If you want to use Navigation, Pagination and other modules, you have to install them first. Here is the list of additional modules imports:

Virtual - Virtual Slides module
Keyboard - Keyboard Control module
Mousewheel - Mousewheel Control module
Navigation - Navigation module
Pagination - Pagination module
Scrollbar - Scrollbar module
Parallax - Parallax module
Zoom - Zoom module
Lazy - Lazy module
Controller - Controller module
A11y - Accessibility module
History - History Navigation module
HashNavigation - Hash Navigation module
Autoplay - Autoplay module
EffectFade - Fade Effect module
EffectCube - Cube Effect module
EffectFlip - Flip Effect module
EffectCoverflow - Coverflow Effect module
Thumbs - Thumbs module

// import Swiper core and required modules
import SwiperCore, { Navigation, Pagination, Scrollbar, A11y } from 'swiper';

import { Swiper, SwiperSlide } from 'swiper/react';

// Import Swiper styles
import 'swiper/swiper.scss';
import 'swiper/components/navigation/navigation.scss';
import 'swiper/components/pagination/pagination.scss';
import 'swiper/components/scrollbar/scrollbar.scss';

// install Swiper modules
SwiperCore.use([Navigation, Pagination, Scrollbar, A11y]);

export default () => {
  return (
    <Swiper
      spaceBetween={50}
      slidesPerView={3}
      navigation
      pagination={{ clickable: true }}
      scrollbar={{ draggable: true }}
      onSwiper={(swiper) => console.log(swiper)}
      onSlideChange={() => console.log('slide change')}
    >
      <SwiperSlide>Slide 1</SwiperSlide>
      <SwiperSlide>Slide 2</SwiperSlide>
      <SwiperSlide>Slide 3</SwiperSlide>
      <SwiperSlide>Slide 4</SwiperSlide>
      ...
    </Swiper>
  );
};

Note, Swiper React component will create required elements for Navigation, Pagination and Scrollbar if you pass these params without specifying its elements (e.g. without navigation.nextEl, pagination.el, etc.)

Styles

Swiper package contains different sets of CSS, Less and SCSS styles:

CSS Styles

CSS styles available only for bundle version:

swiper-bundle.css - all Swiper styles including all modules styles (like Navigation, Pagination, etc.)
swiper-bundle.min.css - same as previous but minified

Less Styles

Less styles are separate styles for core version and modules:

swiper.less - only core Swiper styles
components/a11y/a11y.less - styles required for A11y module
components/controller/controller.less - styles required for Controller module
components/effect-coverflow/effect-coverflow.less - styles required for Coverflow Effect module
components/effect-cube/effect-cube.less - styles required for Cube Effect module
components/effect-fade/effect-fade.less - styles required for Fade Effect module
components/effect-flip/effect-flip.less - styles required for Flip Effect module
components/lazy/lazy.less - styles required for Lazy module
components/navigation/navigation.less - styles required for Navigation module
components/pagination/pagination.less - styles required for Pagination module
components/scrollbar/scrollbar.less - styles required for Scrollbar module
components/thumbs/thumbs.less - styles required for Thumbs module
components/zoom/zoom.less - styles required for Zoom module

SCSS Styles

SCSS styles are also separate styles for core version and modules:

swiper.scss - only core Swiper styles
components/a11y/a11y.scss - styles required for A11y module
components/controller/controller.scss - styles required for Controller module
components/effect-coverflow/effect-coverflow.scss - styles required for Coverflow Effect module
components/effect-cube/effect-cube.scss - styles required for Cube Effect module
components/effect-fade/effect-fade.scss - styles required for Fade Effect module
components/effect-flip/effect-flip.scss - styles required for Flip Effect module
components/lazy/lazy.scss - styles required for Lazy module
components/navigation/navigation.scss - styles required for Navigation module
components/pagination/pagination.scss - styles required for Pagination module
components/scrollbar/scrollbar.scss - styles required for Scrollbar module
components/thumbs/thumbs.scss - styles required for Thumbs module
components/zoom/zoom.scss - styles required for Zoom module

Swiper props

Swiper React component receive all Swiper parameters as component props, plus some extra props:

Prop	Type	Default	Description
`tag`	`string`	`'div'`	Main Swiper container HTML element tag
`wrapperTag`	`string`	`'div'`	Swiper wrapper HTML element tag
`onSwiper`	`(swiper) => void`	`'div'`	Callback that receives Swiper instance

Also it supports all Swiper events in on{Eventname} format. For example slideChange event becomes onSlideChange prop:

  <Swiper
    onSlideChange={() => {/*...*/}}
    onReachEnd={() => {/*...*/}}
    ...
  >

SwiperSlide props

Prop	Type	Default	Description
`tag`	`string`	`'div'`	Swiper Slide HTML element tag
`zoom`	`boolean`	`false`	Enables additional wrapper required for zoom mode
`virtualIndex`	`number`		Actual swiper slide index. Required to be set for virtual slides

SwiperSlide render function

SwiperSlide component can accept render function that receives an object with the following properties:

isActive - true when current slide is active
isPrev - true when current slide is the previous from active
isNext - true when current slide is the next from active
isVisible - true when current slide is visible (watchSlidesVisibility Swiper parameter must be enabled)
isDuplicate - true when current slide is a duplicate slide (when loop mode enabled) For example:

<Swiper>
  <SwiperSlide>
    {({ isActive }) => (
      <div>Current slide is {isActive ? 'active' : 'not active'}</div>
    )}
  </SwiperSlide>
</Swiper>

Slots

Swiper React uses "slots" for content distribution. There are 4 slots available

container-start - element will be added to the beginning of swiper-container
container-end (default) - element will be added to the end of swiper-container
wrapper-start - element will be added to the beginning of swiper-wrapper
wrapper-end - element will be added to the end of swiper-wrapper

For example:

<Swiper>
  <SwiperSlide>Slide 1</SwiperSlide>
  <SwiperSlide>Slide 2</SwiperSlide>
  <span slot="container-start">Container Start</span>
  <span slot="container-end">Container End</span>
  <span slot="wrapper-start">Wrapper Start</span>
  <span slot="wrapper-end">Wrapper End</span>
</Swiper>

Will be rendered as:

<div class="swiper-container">
  <span slot="container-start">Container Start</span>
  <div class="swiper-wrapper">
    <span slot="wrapper-start">Wrapper Start</span>
    <div class="swiper-slide">Slide 1</div>
    <div class="swiper-slide">Slide 2</div>
    <span slot="wrapper-end">Wrapper End</span>
  </div>
  <span slot="container-end">Container End</span>
</div>

Virtual Slides

Virtual Slides rendering here is fully handled by React and not required anything except setting virtual:true property and setting virtualIndex on slides:

import SwiperCore, { Virtual } from 'swiper';
import { Swiper, SwiperSlide } from 'swiper/react';

// Import Swiper styles
import 'swiper/swiper.min.css';

// install Virtual module
SwiperCore.use([Virtual]);

export default () => {
  // Create array with 1000 slides
  const slides = Array.from({ length: 1000 }).map(
    (el, index) => `Slide ${index + 1}`
  );

  return (
    <Swiper spaceBetween={50} slidesPerView={3} virtual>
      {slides.map((slideContent, index) => (
        <SwiperSlide key={slideContent} virtualIndex={index}>
          {slideContent}
        </SwiperSlide>
      ))}
    </Swiper>
  );
};

Controller

Controller requires to pass one Swiper instance to another:

  import React, { useState } from 'react';
  import SwiperCore, { Controller } from 'swiper';
  import { Swiper, SwiperSlide } from 'swiper/react';

  // install Swiper's Controller component
  SwiperCore.use([Controller]);

  const App = () => {
    // store controlled swiper instance
    const [controlledSwiper, setControlledSwiper] = useState(null);

    return (
      <main>
        {/* Main Swiper -> pass controlled swiper instance */}
        <Swiper controller={{ control: controlledSwiper }} ...>
          {/* ... */}
        </Swiper>

        {/* Controlled Swiper -> store swiper instance */}
        <Swiper onSwiper={setControlledSwiper} ...>
          {/* ... */}
        </Swiper>
      </main>
    )
  }

For two-way control (when both Swipers control each other) it should be like this:

import React, { useState } from 'react';
import SwiperCore, { Controller } from 'swiper';
import { Swiper, SwiperSlide } from 'swiper/react';

// install Swiper's Controller component
SwiperCore.use([Controller]);

const App = () => {
  // store swiper instances
  const [firstSwiper, setFirstSwiper] = useState(null);
  const [secondSwiper, setSecondSwiper] = useState(null);

  return (
    <main>
      <Swiper onSwiper={setFirstSwiper} controller={{ control: secondSwiper }}>
        {/* ... */}
      </Swiper>

      <Swiper onSwiper={setSecondSwiper} controller={{ control: firstSwiper }}>
        {/* ... */}
      </Swiper>
    </main>
  );
};

Thumbs

Same as with controller we need to store thumbs instance and pass it to main gallery:

  import React, { useState } from 'react';
  import { Swiper, SwiperSlide } from 'swiper/react';
  import SwiperCore, { Thumbs } from 'swiper/core';

  // install Swiper's Thumbs component
  SwiperCore.use([Thumbs]);

  const App = () => {
    // store thumbs swiper instance
    const [thumbsSwiper, setThumbsSwiper] = useState(null);

    return (
      <main>
        {/* Main Swiper -> pass thumbs swiper instance */}
        <Swiper thumbs={{ swiper: thumbsSwiper }} ...>
          {/* ... */}
        </Swiper>

        {/* Thumbs Swiper -> store swiper instance */}
        {/* It is also required to set watchSlidesVisibility and watchSlidesProgress props */ }
        <Swiper
          onSwiper={setThumbsSwiper}
          watchSlidesVisibility
          watchSlidesProgress
          ...
        >
          {/* ... */}
        </Swiper>
      </main>
    )
  }

Effects

The following effects are available:

- Fade
- Cube
- Coverflow
- Flip

To use effects you have to import and install them first (as all other modules) (Fade example):

import SwiperCore, { EffectFade } from 'swiper';
SwiperCore.use([EffectFade]);

You can find running effect demos here.

Full Fade Effect Example

import React from 'react';
import { Swiper, SwiperSlide } from 'swiper/react';
import SwiperCore, { EffectFade } from 'swiper';

import 'swiper/swiper.scss';
import 'swiper/components/effect-fade/effect-fade.scss';

SwiperCore.use([EffectFade]);

export default () => {
  return (
    <Swiper effect="fade">
      {[1, 2, 3].map((i, el) => {
        return <SwiperSlide>Slide {el}</SwiperSlide>;
      })}
    </Swiper>
  );
};

Getting Started Video

For a more comprehensive hands-on tutorial have a look at this 15-min getting-started video