Usage

1. Download the latest version of Swiper from GitHub here .

2. Add to HEAD Swiper's CSS and JS :

<head>
  ....
  <link rel="stylesheet" href="path_to_css/idangerous.swiper.css">
  <script defer src="path_to_js/idangerous.swiper-2.x.min.js"></script>
  ....
</head>
      

3. Use the following HTML layout:

<div class="swiper-container">
  <div class="swiper-wrapper">
      <!--First Slide-->
      <div class="swiper-slide"> 
        <!-- Any HTML content of the first slide goes here -->
      </div>
      
      <!--Second Slide-->
      <div class="swiper-slide">
        <!-- Any HTML content of the second slide goes here -->
      </div>
      
      <!--Third Slide-->
      <div class="swiper-slide"> 
        <!-- Any HTML content of the third slide goes here -->
      </div>
      <!--Etc..-->
  </div>
</div>

    

4. Open idangerous.swiper.css and set the Swiper's width and height (in the end of the file):

...
/* Specify Swiper's Size: */
.swiper-container, .swiper-slide {
  width: 500px;
  height: 200px;
}
    

5. Initialize Swiper on document ready (or when window is loaded):

<script type="text/javascript">
/*======
Use document ready or window load events
For example:
With jQuery: $(function() { ...code here... })
Or window.onload = function() { ...code here ...}
Or document.addEventListener('DOMContentLoaded', function(){ ...code here... }, false)
=======*/

window.onload = function() {
  var mySwiper = new Swiper('.swiper-container',{
    //Your options here:
    mode:'horizontal',
    loop: true
    //etc..
  });  
}

/*
Or with jQuery/Zepto
*/
$(function(){
  var mySwiper = $('.swiper-container').swiper({
    //Your options here:
    mode:'horizontal',
    loop: true
    //etc..
  });
})

</script>

    

API

new Swiper(container, options)

OR:

Usage:

var mySwiper = new Swiper('.swiper-container', { 
  speed:750, 
  mode:'vertical'
})
    

Returns the object with couple of useful functions and methods:

Options

Swiper support the following list of parameters on initialization:

Parameter Type Default Value Example Description
speed number 300 600 duration of animation between slides (in ms)
eventTarget string 'wrapper' 'container' Event target for swipes, by default all touch events are used on wrapper. Useful to switch it to 'container' if you have some other elements inside of container and you want to keep swipes on them.
autoplay number 5000 - delay between transitions (in ms). If this parameter is not specified, auto play will be disabled
autoplayDisableOnInteraction boolean true false Set to false and autoplay will not be disabled after user interactions(swipes, arrow and pagination clicks), it will be restarted every time after interaction.
autoplayStopOnLast boolean false true Set to false and autoplay will be disabled on last slide (works only with disabled loop).
mode string 'horizontal' 'vertical' slides will be positioned horizontally (for horizontal swipes) or vertically (for vertical swipes)
loop boolean false true Set to true to enable loop mode.
loopAdditionalSlides number 0 2 Addition number of slides that will be cloned after creating of loop.
loopedSlides number 1 2 If you use slidesPerView:'auto' with loop mode you should tell to Swiper how many slides it should "loop" using this parameter.
slidesPerView number
or
'auto'
1 4 Set numbers of slides you want to display at the same time on slider's container for carousel mode. Also supports for 'auto' value, in this case it will fit slides depending on container's width. 'auto' mode doesn't compatible with loop mode.
slidesPerViewFit boolean true false Will make effect only with slidesPerView:'auto' and if you have slides that are wider than container. When true (by default) then large slide transition will be divided on two part on its edge positions. When false - slide transition will be divided as many parts as slide larger than container.
slidesPerGroup number 1 2 Set numbers of slides to define and enable group sliding. Useful to use with carousel mode.
calculateHeight boolean false true Set to true and Swiper will calculate container's height depending on slides content. Useful in repsonsive layout or when you don't know height of your slides (like with responsive images).
roundLengths boolean false true Set to true and Swiper will round width/height values, may be useful if you have rounding errors (like 833.48px width) in responsive swiper.
cssWidthAndHeight boolean/string false true
'width'
'height'
Set to true and Swiper will not set width and height to container, wrapper and slides. You can also set only 'width' or 'height' and Swiper will not set related size
updateOnImagesReady boolean true false When enabled Swiper will be reinitialized after all inner images (<img> tags) are loaded. .
releaseFormElements boolean true false This option allows to use form elements in Swiper and disable swiping on them. .
watchActiveIndex boolean false true If enabled the Swipe recalculates activeIndex dynamically during touch interactions .
visibilityFullFit boolean false true If enabled then "visible" slides will be only those slides that are entirely fit to the container's view. .
autoResize boolean true false Set to false if you want to disable automatic slider resize on window resize. .
resizeReInit boolean false true If "true" then Swiper will be always reinitialized with window resize. .
DOMAnimation boolean true false Enable/disable custom DOM animation in browsers that don't support css transitions (like IE7-9). .
resistance boolean
or
'100%'
true false Set to false if you want to disable resistant bounds. Set to '100%' to enable nopeek resistance mode. .
noSwiping boolean false true If true, then you can add "noSwipingClass" class to swiper's slide to prevent/disable swiping on this element. .
preventLinks boolean true false When enabled Swiper will prevent clicks on links (<a>) while slider is "touching".
preventLinksPropagation boolean false true Set to true if you want to do stopPropagation along with preventLinks during swipes.
initialSlide number 2 0 Index number of initial slide.
useCSS3Transforms boolean true false Set to false if you don't want to use css3 transforms for slides offset (could improve quality, but could reduce performance) to use wrapper's left/top properties instead.
Free Mode and Scroll Container
freeMode boolean false true If 'true' then slides will not have fixed positions
freeModeFluid boolean false true If true, then if you release the slide it will keep moving for a while
scrollContainer boolean false true Set to true if you want to use Swiper like a scrollable area.
momentumRatio number 1 2 Higher value produces larger momentum distance after you release slider.
momentumBounce boolean true false Set to false if you want to disable momentum bounce in free mode.
momentumBounceRatio number 1 2 Higher value produces larger momentum bounce effect.
Slides offset
centeredSlides boolean false true If true, then active slide will be centered, not always on the left side. .
offsetPxBefore number 0 100 Slides will have specified offset value from the left "border" of wrapper .
offsetPxAfter number 0 100 Slides will have specified offset value from the right "border" of wrapper .
offsetSlidesBefore number 0 2 Slides will have offset from the left "border" of wrapper that equal to the specified number of slides' widths. Useful in responsive layouts when you don't know slide's width .
offsetSlidesAfter number 0 2 Slides will have offset from the right "border" of wrapper that equal to the specified number of slides' widths. Useful in responsive layouts when you don't know slide's width .
Touch/mouse interactions
touchRatio number 1 0.8 Touch ratio
simulateTouch boolean true false If true, Swiper will accept mouse events like touch events (click and drag to change slides)
onlyExternal boolean false true If true, then the only way to switch the slide is use of external API functions like swipeRight or swipeLeft. Useful for tabs like in example above
followFinger boolean true false If false, then slider will be animated only when you release it, it will not move while you hold your finger on it
grabCursor boolean false true This option may a little improve usability of your swiper users. If true, user will see the "grab" cursor when hover on Swiper.
shortSwipes boolean true false Set to false if you want to disable short swipes.
longSwipesRatio number 0.5 0.3 Ratio to trigger swipe to next/previous slide during long swipes.
moveStartThreshold number false 100 Threshold value in px. If "touch distance" will be lower than this value then swiper will not move.
swipeToNext boolean true false Set to false to disable swiping to next direction (to right or bottom)New in 2.7.0
swipeToPrev boolean true false Set to false to disable swiping to prev direction (to left or top)New in 2.7.0
Navigation
keyboardControl boolean false true Set to true to enable navigation through slides using keyboard right and left (for horizontal mode), top and borrom (for vertical mode) keyboard arrows
mousewheelControl boolean false true Set to true to enable navigation through slides using mouse wheel.
mousewheelControlForceToAxis boolean false true Set to true to force mousewheel swipes to axis. So in horizontal mode mousewheel will work only with horizontal mousewheel scrolling, and only with vertical scrolling in vertical mode.
Pagination
pagination string or HTML Element - '.my-pagination' CSS selector of the container with pagination. Or HTML element of pagination element.
paginationClickable boolean false true If true then clicking on pagination button will cause transition to appropriate slide. .
paginationAsRange boolean true If true then pagination buttons that are related to visible slides will have additional css class. Useful when using slidesPerView more than 1. .
createPagination boolean true false if true, then Swiper will create as many SPAN elements as many slides in slider. All these spans will be created in the container specified in the "pagination" parameter. Every SPAN will have a 'swiper-pagination-switch' class, active span (of the current slide) will have a 'swiper-active-switch' class. They will be useful for styling them.
Namespace
wrapperClass string 'swiper-wrapper' 'my-wrapper' CSS class of the Swiper's wrapper. See the HTML demo above
slideClass string 'swiper-slide' 'my-slide' CSS class of the Swiper's slide. See the HTML demo above
slideActiveClass string 'swiper-slide-active' 'my-active-slide' CSS class of the Swiper's active slide. .
slideVisibleClass string 'swiper-slide-visible' 'my-visible-slide' CSS class of the Swiper's visible slide. .
slideElement string 'div' 'li' Name of tag that you use for single slide.
noSwipingClass string 'swiper-no-swiping' 'stop-swiping' CSS class of html element that will be used to prevent swiping when "noSwiping" parameter is set to true. .
paginationElement string 'span' 'div' Name of tag that you use for single pagination button.
paginationElementClass string 'swiper-pagination-switch' 'my-switch' CSS class of the Swiper's pagination switch. .
paginationActiveClass string 'swiper-active-switch' 'my-active-switch' CSS class of the Swiper's active pagination switch.
paginationVisibleClass string 'swiper-visible-switch' 'my-visible-switch' CSS class of the Swiper's visible pagination switch. .
Callbacks
queueStartCallbacks boolean false true Set to "true" if you want to queue "slideChangeStart" callbacks. In this case callback will be fired only once during fast multiple swipes/transitions. .
queueEndCallbacks boolean false true Set to "true" if you want to queue "slideChangeEnd" callbacks. In this case callback will be fired only once after fast multiple swipes/transitions. .
onFirstInit function - function(swiper){ do something } Callback function, will be executed right after first initialization.
onInit function - function(swiper){ do something } Callback function, will be executed right after all others initializations/re-intializations.
onSwiperCreated function - function(swiper){ do something } Callback function, when Swiper is fully initialized, after creation of loop, pagination, etc.
onTouchStart function - function(swiper){ do something } Callback function, will be executed when you touch the slider
onTouchMove function - function(swiper){ do something } Callback function, will be executed when you touch and move finger over the slider
onTouchEnd function - function(swiper){ do something } Callback function, will be executed when you release the slider
onSlideReset function - function(swiper){ do something } Callback function, will be executed when you release the slide and it going to be reseted to currently active slide. Don't work with freeMode.
onSlideChangeStart function - function(swiper, direction){ do something } Callback function, will be executed in the beginning of animation to other slide (next or previous). Don't work with freeMode.
onSlideChangeEnd function - function(swiper, direction){ do something } Callback function, will be executed after animation to other slide (next or previous). Don't work with freeMode.
onSlideNext function - function(swiper){ do something } Callback function, the same as onSlideChangeStart but only for forward direction.
onSlidePrev function - function(swiper){ do something } Callback function, the same as onSlideChangeStart but only for backward direction.
onSlideClick function - function(swiper){ do something } Callback function, will be executed after you click any slide.
onSlideTouch function - function(swiper){ do something } Callback function, will be executed right after you touch any slide. Almost the same as onTouchStart , but also returns .clickedSlide and .clikedSlideIndex values.
onImagesReady function - function(swiper){ do something } Callback function, will be executed right after all inner images are loaded. "updateOnImagesReady" should be also set to "true". .
onMomentumBounce function - function(swiper){ do something } Callback function, will be executed on momentum bounce. .
onResistanceBefore function - function(swiper,p){ do something } Callback function, will be executed during negative resistance. p - returns resistance distance. .
onResistanceAfter function - function(swiper,p){ do something } Callback function, will be executed during positive resistance. p - returns resistance distance. .
onSetWrapperTransition function - function(swiper, duration){ do something } Callback function, will be executed everytime when swiper starts animation.
onSetWrapperTransform function - function(swiper, transform){ do something } Callback function, will be executed when swiper's wrapper change its position. p - returns object with current transform offset.

Example

<script type="text/javascript">
$(document).ready(function(){
  var mySwiper = $('.swiper-container').swiper({
    mode : 'vertical', //Switch to vertical mode
    speed : 500, //Set animation duration to 500ms
    freeMode : true, //Enable free mode
    freeModeFluid : true, //Enable 'fluid' free mode
    onTouchStart : function() {
      //Do something when you touch the slide
      alert('OMG you touch the slide!') 
    }
  }
})
</script>
    

Callbacks API

Since version 2.4 Swiper comes with improved additive callbacks, now you can add functions to the same callback.

When you initialize Swiper you specify callbacks in old way:

$(document).ready(function(){
  var mySwiper = new Swiper('.swiper-container',{
    mode:'vertical',
    speed: 600,
    onSlideChangeStart: function(swiper){
      alert('Hello 1');
    }
  });  
});
      

And now you can add new function to the callback instead of rewriting onSlideChangeStart parameter entirely:

mySwiper.addCallback('SlideChangeStart', function(swiper){
  alert('Hello 2');
})        
      

And now you will see two alerts "Hello 1" and "Hello 2" in the beginning of transition. In this addCallback method you should specify callback name without "on".

If you need to fire your callback function externally you may use:

mySwiper.fireCallback('SlideChangeEnd', mySwiper);
      

If you need to remove callbacks you need to use:

mySwiper.removeCallbacks('SlideChangeEnd');
      

Slides API

Swiper comes with powerful Slides API that is intended for dynamic slides creation/deletion/manupilation.

Slide Instance

Swiper's Slide instance is the simple HTMLElement but extended with usefull methods

According to the following example mySwiper variable contains Swiper's object with options and methods

<script type="text/javascript">
$(document).ready(function(){
  var mySwiper = $('.swiper-container').swiper({
    mode : 'vertical', //Switch to vertical mode
    speed : 500, //Set animation duration to 500ms
    freeMode : true, //Enable free mode
    freeModeFluid : true, //Enable 'fluid' free mode
    onTouchStart : function() {
      //Do something when you touch the slide
      alert('OMG you touch the slide!') 
    }
  }
})
</script>
    

You can create swiper's slide instance by calling:

mySwiper.createSlide(html, slideClassList, element) where:

var mySwiper = $('.swiper-container').swiper({...some options...})

//Create new instance of slide:

var newSlide = mySwiper.createSlide('<p>Here is my new slide</p>');
// This will generate the following HTML slide: '<div class="swiper-slide"> <p>Here is my new slide</p> </div>'

var newSlide = mySwiper.createSlide('<p>Hello</p>', 'swiper-slide red-slide', 'span');
// This will generate the following HTML slide: '<span class="swiper-slide red-slide"> <p>Hello</p> </span>'

    

After that " newSlide " variable contains just created new instance of Slide, but at the moment it still in the memory, not inside of slider. To add it to slider we can use some of the following chainable methods available on swiper's Slide instance:

//Examples

var mySwiper = $('.swiper-container').swiper({...some options...})

//Create new instance of slide:
var newSlide = mySwiper.createSlide('<p>Here is my new slide</p>');
newSlide.append() // - new slide will be added as the last slide of slider after all existing slides

var newSlide = mySwiper.createSlide('<p>Here is my new slide</p>');
newSlide.prepend() // - new slide will be added as the first slide of slider before all existing slides

//Clone Slide and append
var clonedSlide = newSlide.clone()
clonedSlide.append()

//Crazy Chaining
var newSlide = mySwiper.createSlide('<p>Here is my new slide</p>');
newSlide.prepend().clone().append().clone().insertAfter(2) // - new slide will be added as the first slide of slider before all existing slides, then cloned to new slide that will be added as the last slide of slider after all existing slides, then cloned again to new slide that will be added after the slide with index number equal to 2
    

There are also several helpers methods:

//Examples

var mySwiper = $('.swiper-container').swiper({...some options...})

//Create new instance of slide:
var newSlide = mySwiper.createSlide('<p>Here is my new slide</p>');
newSlide.append().clone().html('<p>New HTML</p>').prepend() 
// new slide will be added as the last slide of slider after all existing slides, then cloned to new slide with other inner html and that will be added as a first slide

var newSlide = mySwiper.createSlide('<p>Here is my new slide</p>');
alert(newSlide.html()) // -> <p>Here is my new slide</p>

Store/Get data:
newSlide.prepend().setData('apples',['iMac', 'MacBook Pro', 'iPhone', 'iPad'])
newSlide.getData('apples') // -> ['iMac', 'MacBook Pro', 'iPhone', 'iPad']

newSlide.data('apple','iPad');
newSlide.data('apple') // ->'iPad'

    

Swiper Slides

Ok, let's look on swiper methods on how to manage existing slides or add/remove slides from "other side":

//Examples:

//Create new slide and append
mySwiper.appendSlide('Hello World')
//OR:
var newSlide = mySwiper.createSlide('Hello World')
mySwiper.appendSlide(newSlide)
//OR:
mySwiper.appendSlide( mySwiper.createSlide('Hello World') )

//Clone first slide and insert to the end
mySwiper.getFirstSlide().clone().append();
//OR:
mySwiper.appendSlide( mySwiper.getSlide(0).clone() )

//Clone second slide with other HTML and insert to the end
mySwiper.getSlide(1).clone().html('Hello New World!').append();

//Remove Last slide
mySwiper.removeLastSlide()

//Remove second slide
mySwiper.removeSlide(1)

//Trick: Swap first and second slides
mySwiper.getSlide(0).insertAfter(1)

//Trick: Move first slide to last postion
mySwiper.getFirstSlide().append()

//Number of slides in slider
alert(mySwiper.slides.length)

//Change HTML of each slide
for (var i = 0; i < mySwiper.slides.length; i++) {
  var slide = mySwiper.slides[i]
  slide.html('<p> My index number is '+i+' </p>')
}
    

Important Notes

When using functions that change number of slides (like append, prepend, remove, etc.), .reInit() function will be called and number of slides will be recalculated automatically. So it is highly don't recommended to add/remove slides dynamically using "slides.length" in "for" loop becausie it may produce infinite loop.