Swiper React Components

Installation

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

  npm i swiper

Usage

swiper/react exports 2 components: Swiper and SwiperSlide:

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

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

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>
  );
};

Here is the list of additional modules imports from swiper/modules:

• Virtual - Virtual Slides module
• Keyboard - Keyboard Control module
• Mousewheel - Mousewheel Control module
• Navigation - Navigation module
• Pagination - Pagination module
• Scrollbar - Scrollbar module
• Parallax - Parallax module
• FreeMode - Free Mode module
• Grid - Grid module
• Manipulation - Slides manipulation module (only for Core version)
• Zoom - Zoom 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
• EffectCards - Cards Effect module
• EffectCreative - Creative Effect module
• Thumbs - Thumbs module

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

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

// Import Swiper styles
import 'swiper/css';
import 'swiper/css/navigation';
import 'swiper/css/pagination';
import 'swiper/css/scrollbar';

export default () => {
  return (
    <Swiper
      // install Swiper modules
      modules={[Navigation, Pagination, Scrollbar, A11y]}
      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>
  );
};

Styles

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

• swiper/css - only core Swiper styles
• swiper/css/bundle - all Swiper styles including all modules styles (like Navigation, Pagination, etc.)

Modules styles (not required if you already imported bundle styles):

• swiper/css/a11y - styles required for A11y module
• swiper/css/autoplay - styles required for Autoplay module
• swiper/css/controller - styles required for Controller module
• swiper/css/effect-cards - styles required for Cards Effect module
• swiper/css/effect-coverflow - styles required for Coverflow Effect module
• swiper/css/effect-creative - styles required for Creative Effect module
• swiper/css/effect-cube - styles required for Cube Effect module
• swiper/css/effect-fade - styles required for Fade Effect module
• swiper/css/effect-flip - styles required for Flip Effect module
• swiper/css/free-mode - styles required for Free Mode module
• swiper/css/grid - styles required for Grid module
• swiper/css/hash-navigation - styles required for Hash Navigation module
• swiper/css/history - styles required for History module
• swiper/css/keyboard - styles required for Keyboard module
• swiper/css/manipulation - styles required for Manipulation module
• swiper/css/mousewheel - styles required for Mousewheel module
• swiper/css/navigation - styles required for Navigation module
• swiper/css/pagination - styles required for Pagination module
• swiper/css/parallax - styles required for Parallax module
• swiper/css/scrollbar - styles required for Scrollbar module
• swiper/css/thumbs - styles required for Thumbs module
• swiper/css/virtual - styles required for Virtual module
• swiper/css/zoom - styles required for Zoom module

For Less styles replace css with less in imports paths, e.g.:

import 'swiper/less';
import 'swiper/less/navigation';
import 'swiper/less/pagination';

For SCSS styles replace css with scss in imports paths, e.g.:

import 'swiper/scss';
import 'swiper/scss/navigation';
import 'swiper/scss/pagination';

Swiper props

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

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

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

SwiperSlide props

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 (watchSlidesProgress 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>

useSwiper

Swiper React provides useSwiper hook to easliy get the Swiper instance in components inside of Swiper:

// some-inner-component.jsx
import { React } from 'react';
import { useSwiper } from 'swiper/react';

export default function SlideNextButton() {
  const swiper = useSwiper();

  return (
    <button onClick={() => swiper.slideNext()}>Slide to the next slide</button>
  );
}

useSwiperSlide

useSwiperSlide is one more hook for components inside of Swiper slides to get the slide data (same data as in SwiperSlide render function)

// some-inner-component.jsx
import { React } from 'react';
import { useSwiperSlide } from 'swiper/react';

export default function SlideTitle() {
  const swiperSlide = useSwiperSlide();

  return (
    <p>Current slide is {swiperSlide.isActive ? 'active' : 'not active'}</p>
  );
}

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">
  <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 { Virtual } from 'swiper/modules';
import { Swiper, SwiperSlide } from 'swiper/react';

// Import Swiper styles
import 'swiper/css';
import 'swiper/css/virtual';

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

  return (
    <Swiper modules={[Virtual]} 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 { Controller } from 'swiper/modules';
  import { Swiper, SwiperSlide } from 'swiper/react';

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

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

        {/* Controlled Swiper -> store swiper instance */}
        <Swiper modules={[Controller]} 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 { Controller } from 'swiper/modules';
import { Swiper, SwiperSlide } from 'swiper/react';

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

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

      <Swiper
        modules={[Controller]}
        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 { Thumbs } from 'swiper/modules';

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

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

        {/* Thumbs Swiper -> store swiper instance */}
        {/* It is also required to set watchSlidesProgress prop */ }
        <Swiper
          modules={[Thumbs]}
          watchSlidesProgress
          onSwiper={setThumbsSwiper}
          ...
        >
          {/* ... */}
        </Swiper>
      </main>
    )
  }

Effects

The following effects are available:

• Fade
• Cube
• Coverflow
• Flip
• Cards
• Creative

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

You can find running effect demos here.

Full Fade Effect Example

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

import 'swiper/css';
import 'swiper/css/effect-fade';

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

Usage with Create React App

Create React App doesn't support pure ESM packages yet. It is still possible to use Swiper (7.2.0+) with it.

In this case we need to use direct file imports:

// Core modules imports are same as usual
import { Navigation, Pagination } from 'swiper/modules';
// Direct React component imports
import { Swiper, SwiperSlide } from 'swiper/swiper-react.mjs';

// Styles must use direct files imports
import 'swiper/swiper.scss'; // core Swiper
import 'swiper/modules/navigation.scss'; // Navigation module
import 'swiper/modules/pagination.scss'; // Pagination module

What next?

As you see it is really easy to integrate Swiper into your website or app. So here are your next steps:

• Go to API Documentation to learn more about all Swiper API and how to control it.
• Look at available Demos.
• If you have questions about Swiper ask them in StackOverflow or Swiper Discussions.
• Create issue on GitHub if you found a bug.