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:

new Swiper(swiperContainer, parameters) - initialize swiper with options

For example:

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

Swiper Parameters

Let's look on list of all available parameters:

Parameter Type Default Description
initialSlide number 0 Index number of initial slide.
direction string 'horizontal' Could be 'horizontal' or 'vertical' (for vertical slider).
speed number 300 Duration of transition between slides (in ms)
Autoplay
autoplay number - delay between transitions (in ms). If this parameter is not specified, auto play will be disabled
autoplayDisableOnInteraction boolean true Set to false and autoplay will not be disabled after user interactions (swipes), it will be restarted every time after interaction
Progress
watchSlidesProgress boolean false Enable this feature to calculate each slides progress
watchVisibility boolean false watchSlidesProgress should be enabled. Enable this option and slides that are in viewport will have additional visible class
Freemode
freeMode boolean false If true then slides will not have fixed positions
freeModeMomentum boolean true If true, then slide will keep moving for a while after you release it
freeModeMomentumRatio number 1 Higher value produces larger momentum distance after you release slider
freeModeMomentumBounce boolean true Set to false if you want to disable momentum bounce in free mode
freeModeMomentumBounceRatio number 1 Higher value produces larger momentum bounce effect
Effects
effect string 'slide' Could be "slide", "fade", "cube" or "coverflow"
fade object
fade: {
  crossFade: false
}
Fade effect parameters
cube object
cube: {
  slideShadows: true,
  shadow: true,
  shadowOffset: 20,
  shadowScale: 0.94
}
Cube effect parameters. For better performance you may disable shadows
coverflow object
coverflow: {
  rotate: 50,
  stretch: 0,
  depth: 100,
  modifier: 1,
  slideShadows : true
}
Coverflow effect parameters. For better performance you may disable shadows
Parallax
parallax boolean false Enable, if you want to use "parallaxed" elements inside of slider
Slides grid
spaceBetween number 0 Distance between slides in px.
slidesPerView number or 'auto' 1 Number of slides per view (slides visible at the same time on slider's container).
slidesPerColumn number 1 Number of slides per column, for multirow layout
slidesPerColumnFill string 'column' Could be 'column' or 'row'. Defines how slides should fill rows, by column or by row
slidesPerGroup number 1 Set numbers of slides to define and enable group sliding. Useful to use with slidesPerView > 1
centeredSlides boolean false If true, then active slide will be centered, not always on the left side.
Grab Cursor
grabCursor boolean false This option may a little improve desktop usability. If true, user will see the "grab" cursor when hover on Swiper
Touches
touchRatio number 1 Touch ration
touchAngle number 45 Allowable angle (in degrees) to trigger touch move
simulateTouch boolean true If true, Swiper will accept mouse events like touch events (click and drag to change slides)
shortSwipes boolean true Set to false if you want to disable short swipes
longSwipes boolean true Set to false if you want to disable long swipes
longSwipesRatio number 0.5 Ratio to trigger swipe to next/previous slide during long swipes
longSwipesMs number 300 Minimal duration (in ms) to trigger swipe to next/previous slide during long swipes
followFinger boolean true If disabled, then slider will be animated only when you release it, it will not move while you hold your finger on it
onlyExternal boolean false If true, then the only way to switch the slide is use of external API functions like slidePrev or slideNext
threshold number 0 Threshold value in px. If "touch distance" will be lower than this value then swiper will not move
touchMoveStopPropagation boolean true If enabled, then propagation of "touchmove" will be stopped
Touch Resistance
resistance boolean true Set to false if you want to disable resistant bounds
resistanceRatio number 0.85 This option allows you to control resistance ratio
Clicks
preventClicks boolean true Set to true to prevent accidental unwanted clicks on links during swiping
preventClicksPropagation boolean true Set to true to stop clicks event propagation on links during swiping
releaseFormElements boolean true Set to true to prevent swiping on form elements
slideToClickedSlide boolean false Set to true and click on any slide will produce transition to this slide
Swiping / No swiping
allowSwipeToPrev boolean true Set to false to disable swiping to previous slide direction (to left or top)
allowSwipeToNext boolean true Set to false to disable swiping to next slide direction (to right or bottom)
noSwiping boolean true Set to false to disable swiping to next slide direction (to right or bottom)
noSwipingClass string 'swiper-no-swiping' If true, then you can add noSwipingClass class to swiper's slide to prevent/disable swiping on this element
swipeHandler string / HTMLElement null String with CSS selector or HTML element of the container with pagination that will work as only available handler for swiping
Pagination
pagination string / HTMLElement null String with CSS selector or HTML element of the container with pagination
paginationHide boolean true Toggle (hide/true) pagination container visibility when click on Slider's container
paginationClickable boolean false If true then clicking on pagination button will cause transition to appropriate slide
Navigation Buttons
nextButton string / HTMLElement null String with CSS selector or HTML element of the element that will work like "next" button after click on it
prevButton string / HTMLElement null String with CSS selector or HTML element of the element that will work like "prev" button after click on it
Scollbar
scrollbar string / HTMLElement null String with CSS selector or HTML element of the container with scrollbar.
scrollbarHide boolean true Hide scrollbar automatically after user interaction
Keyboard / Mousewheel
keyboardControl boolean false 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 Set to true to enable navigation through slides using mouse wheel
mousewheelForceToAxis boolean false 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.
Hash Navigation
hashnav boolean false Set to true to enable hash url navigation to for slides
Images
updateOnImagesReady boolean true When enabled Swiper will be reinitialized after all inner images (<img> tags) are loaded
Loop
loop boolean false

Set to true to enable continuous loop mode

If you use it along with slidesPerView: 'auto' then you need to specify loopedSlides parameter with amount of slides to loop (duplicate)

loopAdditionalSlides number 0 Addition number of slides that will be cloned after creating of loop
loopedSlides number null If you use slidesPerView:'auto' with loop mode you should tell to Swiper how many slides it should loop (duplicate) using this parameter
Controller
control [Swiper Instance] undefined Pass here another Swiper instance or array with Swiper instances that should be controlled by this Swiper
controlInverse boolean false Set to true and controlling will be in inverse direction
Observer
observer boolean false
observeParents boolean false
Callbacks
runCallbacksOnInit boolean true Run on[Transition/SlideChange][Start/End] callbacks on swiper initialization. Such callbacks will be fired on initialization in case of your initialSlide is not 0, or you use loop mode
onInit(swiper) function Callback function, will be executed right after Swiper initialization
onSlideChangeStart(swiper) function Callback function, will be executed in the beginning of animation to other slide (next or previous). Receives swiper instance as an argument.
onSlideChangeEnd(swiper) function Callback function, will be executed after animation to other slide (next or previous). Receives slider instance as an argument.
onTransitionStart(swiper) function Callback function, will be executed in the beginning of transition. Receives swiper instance as an argument.
onTransitionEnd(swiper) function Callback function, will be executed after transition. Receives slider instance as an argument.
onTouchStart(swiper, event) function Callback function, will be executed when user touch Swiper. Receives swiper instance and 'touchstart' event as an arguments.
onTouchMove(swiper, event) function Callback function, will be executed when user touch and move finger over Swiper. Receives swiper instance and 'touchmove' event as an arguments.
onTouchMoveOpposite(swiper, event) function Callback function, will be executed when user touch and move finger over Swiper in direction opposite to direction parameter. Receives swiper instance and 'touchmove' event as an arguments.
onSliderMove(swiper, event) function Callback function, will be executed when user touch and move finger over Swiper and move it. Receives swiper instance and 'touchmove' event as an arguments.
onTouchEnd(swiper, event) function Callback function, will be executed when user release Swiper. Receives swiper instance and 'touchend' event as an arguments.
onClick(swiper, event) function Callback function, will be executed when user click/tap on Swiper after 300ms delay. Receives swiper instance and 'touchend' event as an arguments.
onTap(swiper, event) function Callback function, will be executed when user click/tap on Swiper. Receives swiper instance and 'touchend' event as an arguments.
onDoubleTap(swiper, event) function Callback function, will be executed when user double tap on Swiper's container. Receives swiper instance and 'touchend' event as an arguments
onImagesReady(swiper) function Callback function, will be executed right after all inner images are loaded. updateOnImagesReady should be also enabled
onProgress(swiper, progress) function Callback function, will be executed when Swiper progress is changed, as second arguments it receives progress that is always from 0 to 1
onReachBeginning(swiper) function Callback function, will be executed when Swiper reach its beginning (initial position)
onReachEnd(swiper) function Callback function, will be executed when Swiper reach last slide
onDestroy(swiper) function Callback function, will be executed when you destroy Swiper
onSetTranslate(swiper, translate) function Callback function, will be executed when swiper's wrapper change its position. Receives swiper instance and current translate value as an arguments
onSetTransition(swiper, transition) function Callback function, will be executed everytime when swiper starts animation. Receives swiper instance and current transition duration (in ms) as an arguments
onAutoplayStart(swiper) function Callback function, will be executed when when autoplay started
onAutoplayStop(swiper) function Callback function, will be executed when when autoplay stopped
onSetTransition(swiper, transition) function Callback function, will be executed everytime when swiper starts animation. Receives swiper instance and current transition duration (in ms) as an arguments
Namespace
slideClass string 'swiper-slide' CSS class name of slide
slideActiveClass string 'swiper-slide-active' CSS class name of currently active slide
slideVisibleClass string 'swiper-slide-visible' CSS class name of currently visible slide
slideDuplicateClass string 'swiper-slide-duplicate' CSS class name of slide duplicated by loop mode
slideNextClass string 'swiper-slide-next' CSS class name of slide which is right after currently active slide
slidePrevClass string 'swiper-slide-prev' CSS class name of slide which is right before currently active slide
wrapperClass string 'swiper-wrapper' CSS class name of slides' wrapper
bulletClass string 'swiper-pagination-bullet' CSS class name of single pagination bullet
bulletActiveClass string 'swiper-pagination-bullet-active' CSS class name of currently active pagination bullet
paginationHiddenClass string 'swiper-pagination-hidden' CSS class name of pagination when it becomes inactive
buttonDisabledClass string 'swiper-button-disabled' CSS class name of next/prev button when it becomes disabled

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:

Properties
mySwiper.params Object with passed initialization parameters
mySwiper.container Dom7/jQuery element with slider container HTML element. To get vanilla HTMLElement use mySwiper.container[0]
mySwiper.wrapper Dom7/jQuery element with slider wrapper HTML element. To get vanilla HTMLElement use mySwiper.wrapper[0]
mySwiper.slides Dom7/jQuery array-like collection of slides HTML elements. To get specific slide HTMLElement use mySwiper.slides[1]
mySwiper.bullets Dom7/jQuery collection of pagination buttons HTML elements. To get specific slide HTMLElement use mySwiper.bullets[1]
mySwiper.width Width of container
mySwiper.height Height of container
mySwiper.translate Current value of wrapper translate
mySwiper.progress Current progress of wrapper translate (from 0 to 1)
mySwiper.activeIndex Index number of currently active slide
mySwiper.previousIndex Index number of previously active slide
mySwiper.isBeginning true if slider on most "left"/"top" position
mySwiper.isEnd true if slider on most "right"/"bottom" position
mySwiper.autoplaying true if autoplay is enabled
mySwiper.animating true if swiper is in transition
mySwiper.touches Object with the following touch event properties:
  • mySwiper.touches.startX
  • mySwiper.touches.startY
  • mySwiper.touches.currentX
  • mySwiper.touches.currentY
  • mySwiper.touches.diff
Methods
mySwiper.slideNext(runCallbacks, speed); Run transition to next slide
  • runCallbacks - boolean - Set it to false (by default it is true) and transition will not produce onSlideChange callback functions. Optional
  • speed - number - transition duration (in ms). Optional
mySwiper.slidePrev(runCallbacks, speed); Run transition to previous slide
  • runCallbacks - boolean - Set it to false (by default it is true) and transition will not produce onSlideChange callback functions. Optional
  • speed - number - transition duration (in ms). Optional
mySwiper.slideTo(index, speed, runCallbacks); Run transition to the slide with index number equal to 'index' parameter for the duration equal to 'speed' parameter.
  • index - number - index number of slide
  • speed - number - transition duration (in ms). Optional
  • runCallbacks - boolean - Set it to false (by default it is true) and transition will not produce onSlideChange callback functions. Optional
mySwiper.updateContainerSize(); This method will recalculate size of swiper container
mySwiper.updateSlidesSize(); This method will recalculate number of slides and their offsets. Useful after you add/remove slides with JavaScript
mySwiper.updateProgress(); This method will recalculate swiper progress
mySwiper.updatePagination(); Recalculate slider and slides sizes. Useful after you change slider size with JavaScript
mySwiper.updateClasses(); Updates active/prev/next classes on slides and bullets
mySwiper.update(updateTranslate);

This method includes updateContainerSize, updateSlidesSize, updateProgress, updatePagination and updateClasses methods

You should call it after you add/remove slides manually, or after you hide/show it, or do any custom DOM modifications with Swiper

  • updateTranslate - boolean - Set it to true (by default it is false) to hard set/reset/update Swiper wrapper translate. It is useful if you use not default effect or scrollbar. Optional
mySwiper.onResize(); Swiper executes this method when you resize browser. It is almost the same as .update() but a bit softer, without hard setting translate
mySwiper.detachEvents(); Detach all events listeners
mySwiper.attachEvents(); Atach all events listeners again
mySwiper.startAutoplay(); start auto play. It may be useful for custom "Play" and "Pause" buttons
mySwiper.stopAutoplay(); stop auto play. It may be useful for custom "Play" and "Pause" buttons
mySwiper.destroy(); Destroy slider instance and detach all events listeners
mySwiper.appendSlide(slides); Add new slides to the end. slides could be HTMLElement or HTML string with new slide or array with such slides, for example:
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(slides); Add new slides to the beginning. slides could be HTMLElement or HTML string with new slide or array with such slides, for example:
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.removeSlide(slideIndex); Remove selected slides. slideIndex could be a number with slide index to remove or array with indexes, for example:
mySwiper.removeSlide(0); //remove first slide
mySwiper.removeSlide([0, 1]); //remove first and second slides
mySwiper.removeAllSlides(); Remove all slides
mySwiper.setWrapperTranslate(translate); Set custom css3 transform's translate value for swiper wrapper
mySwiper.getWrapperTranslate(); Get current value of swiper wrapper css3 transform translate
mySwiper.disableMousewheelControl(); Disable mousewheel control
mySwiper.enableMousewheelControl(); Enable mousewheel control
mySwiper.disableKeyboardControl(); Disable keyboard control
mySwiper.enableKeyboardControl(); Enable keyboard control

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 hashnav: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
  hashnav: true
})

Parallax

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

To enable parallax effects you need to init Swiper with passed parallax:true parameter and add data-swiper-parallax attribute on required elements

<div class="swiper-container">
    <!-- Parallax background element -->
    <div 
        class="parallax-bg" 
        style="background-image:url(http://lorempixel.com/900/600/nightlife/2/)" 
        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 -->
            <div class="text" data-swiper-parallax="-300">
              <p>Lorem ipsum dolor sit amet, ...</p>
            </div>
        </div>
        ...
    </div>
</div>

All elements with specified data-swiper-parallax attribute will have parallax transition. This attribute may accept:

It also possible to overwrite parallax direction by using data-swiper-parallax-x and data-swiper-parallax-y attributes with same rules

Access to Swiper's Instance

If you initialize Swiper using HTML it is still possible to access to Swiper's instance. It is swiper property of Swiper's HTML container element:

var mySwiper = $('.swiper-container')[0].swiper;
 
// Now you can use all slider methods like
mySwiper.slideNext();