Swiper API

Swiper Full HTML Layout

<!-- Slider main container -->
<div class="swiper-container">
    <!-- Additional required wrapper -->
    <div class="swiper-wrapper">
        <!-- Slides -->
        <div class="swiper-slide">Slide 1</div>
        <div class="swiper-slide">Slide 2</div>
        <div class="swiper-slide">Slide 3</div>
        ...
    </div>
    <!-- If we need pagination -->
    <div class="swiper-pagination"></div>

    <!-- If we need navigation buttons -->
    <div class="swiper-button-prev"></div>
    <div class="swiper-button-next"></div>

    <!-- If we need scrollbar -->
    <div class="swiper-scrollbar"></div>
</div>

Initialize Swiper

Now, when we have Swiper's HTML, we need to initialize it using the following function:

For example:

var mySwiper = new Swiper('.swiper-container', {
    speed: 400,
    spaceBetween: 100
});

After you initialize Swiper it is possible to access to Swiper's instance on its HTMLElement. It is swiper property of Swiper's HTML container element:

var mySwiper = document.querySelector('.swiper-container').swiper

// Now you can use all slider methods like
mySwiper.slideNext();

Swiper Parameters

Let's look on list of all available parameters:

var swiper = new Swiper('.swiper-container', {
  // Default parameters
  slidesPerView: 1,
  spaceBetween: 10,
  // Responsive breakpoints
  breakpoints: {
    // when window width is >= 320px
    320: {
      slidesPerView: 2,
      spaceBetween: 20
    },
    // when window width is >= 480px
    480: {
      slidesPerView: 3,
      spaceBetween: 30
    },
    // when window width is >= 640px
    640: {
      slidesPerView: 4,
      spaceBetween: 40
    }
  }
})

var swiper = new Swiper('.swiper-container', {
  slidesPerView: 1,
  spaceBetween: 10,
  breakpoints: {
    '@0.75': {
      slidesPerView: 2,
      spaceBetween: 20,
    },
    '@1.00': {
      slidesPerView: 3,
      spaceBetween: 40,
    },
    '@1.50': {
      slidesPerView: 4,
      spaceBetween: 50,
    },
  }
});

Slider Methods & Properties

After we initialize Slider we have its initialized instance in variable (like mySwiper variable in example above) with helpful methods and properties:

mySwiper.appendSlide('<div class="swiper-slide">Slide 10"</div>')
mySwiper.appendSlide([
   '<div class="swiper-slide">Slide 10"</div>',
   '<div class="swiper-slide">Slide 11"</div>'
]);

mySwiper.prependSlide('<div class="swiper-slide">Slide 0"</div>')
mySwiper.prependSlide([
   '<div class="swiper-slide">Slide 1"</div>',
   '<div class="swiper-slide">Slide 2"</div>'
]);

mySwiper.addSlide(1, '<div class="swiper-slide">Slide 10"</div>')
mySwiper.addSlide(1, [
   '<div class="swiper-slide">Slide 10"</div>',
   '<div class="swiper-slide">Slide 11"</div>'
]);

mySwiper.removeSlide(0); //remove first slide
mySwiper.removeSlide([0, 1]); //remove first and second slides

Events

Swiper comes with a bunch of useful events you can listen. Events can be assigned in two ways:

1. Using on parameter on swiper initialization:

   var mySwiper = new Swiper('.swiper-container', {
     // ...
     on: {
       init: function () {
         console.log('swiper initialized');
       },
     },
   };

2. Using on method after swiper initialization.

   var mySwiper = new Swiper('.swiper-container', {
     // ...
   };
   mySwiper.on('slideChange', function () {
     console.log('slide changed');
   });

var swiper = new Swiper('.swiper-container', {
  init: false,
  // other parameters
})
swiper.on('init', function() { /* do something */ });
// init Swiper
swiper.init();

var swiper = new Swiper('.swiper-container', {
  // other parameters
  on: {
    init: function () {
      /* do something */
    },
  }
});

Components

Navigation

Navigation Parameters

var mySwiper = new Swiper('.swiper-container', {
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
});

Navigation Methods & Properties

Navigation Events

Pagination

Pagination Parameters

var mySwiper = new Swiper('.swiper-container', {
  pagination: {
    el: '.swiper-pagination',
    type: 'bullets',
  },
});

var swiper = new Swiper('.swiper-container', {
  //...
  renderBullet: function (index, className) {
    return '<span class="' + className + '">' + (index + 1) + '</span>';
  }
});

var swiper = new Swiper('.swiper-container', {
  //...
  renderFraction: function (currentClass, totalClass) {
      return '<span class="' + currentClass + '"></span>' +
              ' of ' +
              '<span class="' + totalClass + '"></span>';
  }
});

var swiper = new Swiper('.swiper-container', {
  //...
  renderProgressbar: function (progressbarFillClass) {
      return '<span class="' + progressbarFillClass + '"></span>';
  }
});

var swiper = new Swiper('.swiper-container', {
  //...
  renderCustom: function (swiper, current, total) {
      return current + ' of ' + total;
  }
});

Pagination Methods & Properties

Pagination Events

Scrollbar

Scrollbar Parameters

var mySwiper = new Swiper('.swiper-container', {
  scrollbar: {
    el: '.swiper-scrollbar',
    draggable: true,
  },
});

Scrollbar Methods & Properties

Autoplay

Autoplay Parameters

var mySwiper = new Swiper('.swiper-container', {
  autoplay: {
    delay: 5000,
  },
});

<!-- hold this slide for 2 seconds -->
<div class="swiper-slide" data-swiper-autoplay="2000">

Autoplay Methods & Properties

Autoplay Events

Parallax

Swiper supports parallax transition effects for swiper/slides nested elements. There are two types of parallax elements supported:

• Direct child elements of swiper-container. Parallax effect for such elements will depend on total slider progress. Useful for parallax backgrounds
• Slides child elements. Parallax effect for such elements will depend on slide progress

To enable parallax effects you need to init Swiper with passed parallax:true parameter and add one of the following (or mix) attributes to required elements:

• data-swiper-parallax - enable transform-translate parallax transition. This attribute may accept:
  • number - value in px (as for title, subtitle in example above) to move element depending on progress. In this case such element will be moved on ± this value in px depending on slide position (next or previous)
  • percentage - (as for "parallax-bg") to move element depending on progress and on its size. In this case such element will be moved on ± this percentage of its size (width in horizontal direction, and height in vertical direction) depending on slide position (next or previous). So if element has 400px width and you specified data-swiper-parallax="50%" then it will be moved on ± 200px
• data-swiper-parallax-x - same but for x-axis direction
• data-swiper-parallax-y - same but for y-axis direction
• data-swiper-parallax-scale - scale ratio of the parallax element when it is in "inactive" (not on active slide) state
• data-swiper-parallax-opacity - opacity of the parallax element when it is in "inactive" (not on active slide) state
• data-swiper-parallax-duration - custom transition duration for parallax elements

<div class="swiper-container">
  <!-- Parallax background element -->
  <div class="parallax-bg" style="background-image:url(path/to/image.jpg)" data-swiper-parallax="-23%">
  </div>
  <div class="swiper-wrapper">
    <div class="swiper-slide">
      <!-- Each slide has parallax title -->
      <div class="title" data-swiper-parallax="-100">Slide 1</div>
      <!-- Parallax subtitle -->
      <div class="subtitle" data-swiper-parallax="-200">Subtitle</div>
      <!-- And parallax text with custom transition duration -->
      <div class="text" data-swiper-parallax="-300" data-swiper-parallax-duration="600">
        <p>Lorem ipsum dolor sit amet, ...</p>
      </div>
      <!-- Opacity parallax -->
      <div data-swiper-parallax-opacity="0.5">I will change opacity</div>
      <!-- Scale parallax -->
      <div data-swiper-parallax-scale="0.15">I will change scale</div>
    </div>
    ...
  </div>
</div>

Parallax Parameters

Lazy Loading

To enable lazy loading, first of all we need a special layout for images or elements with background in slides:

<div class="swiper-container">
  <div class="swiper-wrapper">

    <!-- Lazy image -->
    <div class="swiper-slide">
      <img data-src="path/to/picture-1.jpg" class="swiper-lazy">
      <div class="swiper-lazy-preloader"></div>
    </div>

    <!-- Lazy image with srscet-->
    <div class="swiper-slide">
      <img data-src="path/to/logo-small.png" data-srcset="path/logo/logo-large.png 2x" class="swiper-lazy">
      <div class="swiper-lazy-preloader"></div>
    </div>

    <!-- Element with lazy background image -->
    <div class="swiper-slide">
      <div data-background="path/to/picture-2.jpg" class="swiper-lazy">
        <div class="swiper-lazy-preloader"></div>
      </div>
    </div>

    <!-- Lazy background image on slide itself -->
    <div data-background="path/to/picture-3.jpg" class="swiper-slide swiper-lazy">
      <div class="swiper-lazy-preloader"></div>
    </div>
  </div>
</div>

As you see:

• Each lazy loaded image/element should have additional "swiper-lazy" class
• Lazy image source for <img> element should be specified in "data-src" attribute instead of "src"
• Lazy image source set for <img> element should be specified in "data-srcset" attribute instead of "srcset"
• Lazy background image source should be specified in "data-background" attribute

You may also add animated preloader spinner to slide which will be removed automatically after image loaded:

<div class="swiper-lazy-preloader"></div>

Or white-one for dark layout:

<div class="swiper-lazy-preloader swiper-lazy-preloader-white"></div>

After that we need to enable lazy loading on Swiper initialization:

var swiper = new Swiper('.swiper-container', {
    // Disable preloading of all images
    preloadImages: false,
    // Enable lazy loading
    lazy: true
});

Lazy Loading Parameters

var mySwiper = new Swiper('.swiper-container', {
  lazy: {
    loadPrevNext: true,
  },
});

Lazy Loading Methods & Properties

Lazy Loading Events

Fade Effect

Fade Effect Parameters

Be sure to have the `effect` param set to `fade` in order for this to work.

var mySwiper = new Swiper('.swiper-container', {
  fadeEffect: {
    crossFade: true
  },
});

Coverflow Effect

Coverflow Effect Parameters

Be sure to have the `effect` param set to `coverflow` in order for this to work.

var mySwiper = new Swiper('.swiper-container', {
  coverflowEffect: {
    rotate: 30,
    slideShadows: false,
  },
});

Flip Effect

Flip Effect Parameters

Be sure to have the `effect` param set to `flip` in order for this to work.

var mySwiper = new Swiper('.swiper-container', {
  flipEffect: {
    rotate: 30,
    slideShadows: false,
  },
});

Cube Effect

Cube Effect Parameters

Be sure to have the `effect` param set to `cube` in order for this to work.

var mySwiper = new Swiper('.swiper-container', {
  cubeEffect: {
    slideShadows: false,
  },
});

Thumbs

In addition to Controller component Swiper comes with Thumbs component that is designed to work with additional thumbs swiper in a more correct way than Controller which is used for syncing two swipers.

Thumbs Parameters

var mySwiper = new Swiper('.swiper-container', {
  ...
  thumbs: {
    swiper: thumbsSwiper
  }
});

var thumbsSwiper = new Swiper('.swiper-container-thumbs', {
  slidesPerView: 5,
});

var mySwiper = new Swiper('.swiper-container', {
  ...
  thumbs: {
    swiper: thumbsSwiper
  }
});

var mySwiper = new Swiper('.swiper-container', {
  ...
  thumbs: {
    swiper: {
      el: '.swiper-container-thumbs',
      slidesPerView: 5,
      ...
    }
  }
});

Thumbs Methods & Properties

Zoom

Swiper supports zoom images functionality (similar to what you see on iOS when browsing single photo) where you can zoom-in image by pinch gesture and or by zoom-in/out by double tap on it. In this case, additional layout is required:

<div class="swiper-container">
    <div class="swiper-wrapper">
        <div class="swiper-slide">
            <div class="swiper-zoom-container">
                <img src="path/to/image1.jpg">
            </div>
        </div>
        <div class="swiper-slide">
            <div class="swiper-zoom-container">
                <img src="path/to/image2.jpg">
            </div>
        </div>
        <div class="swiper-slide">Plain slide with text</div>
        <div class="swiper-slide">
            <!-- Override maxRatio parameter -->
            <div class="swiper-zoom-container" data-swiper-zoom="5">
                <img src="path/to/image1.jpg">
            </div>
        </div>
    </div>
</div>

• All "zoomable" images should be wrapped with the div with swiper-zoom-container class.

• By default it expects to zoom one of the img, picture or canvas element. If you want to make zoom on some other custom element, then just add swiper-zoom-target class to this element. For example:

  <div class="swiper-container">
    <div class="swiper-wrapper">
      <div class="swiper-slide">
        <div class="swiper-zoom-container">
          <!-- custom zoomable element -->
          <div class="swiper-zoom-target" style="background-image: url(...)"></div>
        </div>
      </div>
  </div>

• You can override maxRatio parameter for specific slides by using data-swiper-zoom attribute on zoom container.

Zoom Parameters

var mySwiper = new Swiper('.swiper-container', {
  zoom: {
    maxRatio: 5,
  },
});

Zoom Methods & Properties

Zoom Events

Keyboard Control

Keyboard Control Parameters

var mySwiper = new Swiper('.swiper-container', {
  keyboard: {
    enabled: true,
    onlyInViewport: false,
  },
});

Keyboard Methods & Properties

Mousewheel Control

Mousewheel Control Parameters

var mySwiper = new Swiper('.swiper-container', {
  mousewheel: {
    invert: true,
  },
});

Mousewheel Methods & Properties

Virtual Slides

Virtual Slides module allows to keep just required amount of slides in DOM. It is very useful in terms in performance and memory issues if you have a lot of slides, especially slides with heavyweight DOM tree or images.

Virtual Slides Parameters

var mySwiper = new Swiper('.swiper-container', {
  virtual: {
    slides: ['Slide 1', 'Slide 2', 'Slide 3', 'Slide 4', 'Slide 5'],
  },
});

Virtual Slides Methods & Properties

renderExternal Example

renderExternal allows to bypass slides rendering to other libraries, and can be super handy with libraries like React.js and Vue.js

With Vue.js

<template>
  <!-- ... -->
  <div class="swiper-container">
    <div class="swiper-wrapper">
      <!-- It is important to set "left" style prop on every slide -->
      <div class="swiper-slide"
        v-for="(slide, index) in virtualData.slides"
        :key="index"
        :style="{left: `${virtualData.offset}px`}"
      >{{slide}}</div>
    </div>
  </div>
  <!-- ... -->
</template>
<script>
  import Swiper from 'swiper/js/swiper.esm.bundle';

  export default {
    data() {
      return {
        // dummy slides data
        slides: (function () {
          var slides = [];
          for (var i = 0; i < 600; i += 1) {
            slides.push('Slide ' + (i + 1));
          }
          return slides;
        }()),
        // virtual data
        virtualData: {
          slides: [],
        },
      }
    },
    mounted() {
      const self = this;
      const swiper = new Swiper('.swiper-container', {
        // ...
        virtual: {
          slides: self.slides,
          renderExternal(data) {
            // assign virtual slides data
            self.virtualData = data;
          },
        },
      });
    },
  };
</script>

With React.js

import React from 'react';
import Swiper from 'swiper/js/swiper.esm.bundle';

export default class extends React.Component {
  constructor() {
    this.state = {
      // dummy slides data
      slides: (function () {
        var slides = [];
        for (var i = 0; i < 600; i += 1) {
          slides.push('Slide ' + (i + 1));
        }
        return slides;
      }()),
      // virtual data
      virtualData: {
        slides: [],
      },
    }
  }
  componentDidMount() {
    const self = this;
    const swiper = new Swiper('.swiper-container', {
      // ...
      virtual: {
        slides: self.state.slides,
        renderExternal(data) {
          // assign virtual slides data
          self.setState({
            virtualData: data,
          });
        }
      },
    });
  }
  render() {
    {/* ... */}
    <div className="swiper-container">
      <div className="swiper-wrapper">
        {/* It is important to set "left" style prop on every slide */}
        {this.state.virtualData.slides.map((slide, index) => (
          <div className="swiper-slide"
            key={index}
            style={{left: `${virtualData.offset}px`}}
          >{slide}</div>
        ))}
      </div>
    </div>
    {/* ... */}
  }
}

Hash Navigation

Hash navigation is intended to have a link to specific slide that allows to load page with specific slide opened.

To make it work, you need to enable it by passing hashNavigation:true parameter and adding slides hashes in data-hash attribute:

<div class="swiper-container">
    <div class="swiper-wrapper">
        <div class="swiper-slide" data-hash="slide1">Slide 1</div>
        <div class="swiper-slide" data-hash="slide2">Slide 2</div>
        <div class="swiper-slide" data-hash="slide3">Slide 3</div>
        <div class="swiper-slide" data-hash="slide4">Slide 4</div>
        <div class="swiper-slide" data-hash="slide5">Slide 5</div>
        ...
    </div>
</div>

var swiper = new Swiper('.swiper-container', {
  //enable hash navigation
  hashNavigation: true
})

Hash Navigation Parameters

var mySwiper = new Swiper('.swiper-container', {
  hashNavigation: {
    replaceState: true,
  },
});

Hash Navigation Events

History Navigation

History Navigation Parameters

var mySwiper = new Swiper('.swiper-container', {
  history: {
    replaceState: true,
  },
});

<!-- will produce "slides/slide1" url in browser history -->
<div class="swiper-slide" data-history="slide1"></div>

Controller

Controller Parameters

var mySwiper = new Swiper('.swiper-container', {
  controller: {
    inverse: true,
  },
});

Accessibility (a11y)

Accessibility Parameters

var mySwiper = new Swiper('.swiper-container', {
  a11y: {
    prevSlideMessage: 'Previous slide',
    nextSlideMessage: 'Next slide',
  },
});

Custom Build

You have two options of making custom version of Swiper.

1. Using ES-module

If you use bundler with ES-modules support in your project you can import only the modules you need:

// Import Swiper and modules
import { Swiper, Navigation, Pagination, Scrollbar } from 'swiper/js/swiper.esm.js';

// Install modules
Swiper.use([Navigation, Pagination, Scrollbar]);

// Now you can use Swiper
var swiper = new Swiper('.swiper-container', {
  speed: 500,
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
  // ...
});

The following modules are exported from swiper.esm.js:

• Swiper - core library
• 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

2. Using Build Script

Swiper comes with gulp builder that allows to build custom library version where you may include only required modules. We need the following:

1. Download and unzip Swiper GitHub repository to local folder
2. Install Node.js (if not installed)
3. Install Gulp (if not installed) by executing the following command in terminal:

   $ npm install --global gulp

4. Now, we need to install required dependencies. Go to the folder with downloaded and unzipped Swiper repository and execute in terminal:

   $ npm install

5. Open scripts/build-config.js file:

   module.exports = {
     // remove components you don't need
     components: [
       'virtual',
       'keyboard',
       'mousewheel',
       'navigation',
       'pagination',
       'scrollbar',
       'parallax',
       'zoom',
       'lazy',
       'controller',
       'a11y',
       'history',
       'hash-navigation',
       'autoplay',
       'effect-fade',
       'effect-cube',
       'effect-flip',
       'effect-coverflow',
     ],
     // target device, can be "desktop" or "universal"
     target: 'universal',
     // default color of navigation elements
     themeColor: '#007aff',
     // additional color to be included
     colors: {
       white: '#ffffff',
       black: '#000000',
     },
   };

6. Now, we are ready to build custom version of Swiper:

   $ npm run build:prod

7. That is all. Generated CSS and JS files and their minified versions will be available in package/ folder.