Back to post

Swiper is the most modern and flexible mobile touch slider with a lot of parameters, you can control slides per view, per column, per group, space between slides, and many more.

Features:

Install with npm

$ npm install swiper

How to use it:

1. Include the Javascript swiper.min.js at the bottom of the web page.

<script src="path/to/swiper.min.js"></script>

2. Include the CSS swiper.min.css in the header of the page.

<link rel="stylesheet" href="path/to/swiper.min.css">

3. Add the basic HTML to the page.

<div class="swiper-container">
  <div class="swiper-wrapper">
    <div class="swiper-slide"><img src="path/to/demo-1.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-2.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-3.jpg" /></div>
  </div>
</div>

4. Initialize the plugin and we're ready to go. 

var swiper = new Swiper('.swiper-container');

Plugin's default options:

Parameter Type Default Description
init boolean true Whether Swiper should be initialised automatically when you create an instance. If disabled, then you need to init it manually by calling mySwiper.init()
updateOnWindowResize boolean true Swiper will recalculate slides position on window resize (orientationchange)
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)
setWrapperSize boolean false Enabled this option and plugin will set width/height on swiper wrapper equal to total size of all slides. Mostly should be used as compatibility fallback option for browser that don't support flexbox layout well
virtualTranslate boolean false Enabled this option and swiper will be operated as usual except it will not move, real translate values on wrapper will not be set. Useful when you may need to create custom slide transition
width number Swiper width (in px). Parameter allows to force Swiper width. Useful only if you initialize Swiper when it is hidden.
Setting this parameter will make Swiper not responsive
height number Swiper height (in px). Parameter allows to force Swiper height. Useful only if you initialize Swiper when it is hidden.
Setting this parameter will make Swiper not responsive
autoHeight boolean false Set to true and slider wrapper will adopt its height to the height of the currently active slide
roundLengths boolean false Set to true to round values of slides width and height to prevent blurry texts on usual resolution screens (if you have such)
nested boolean false Set to true on nested Swiper for correct touch events interception. Use only on nested swipers that use same direction as the parent one
uniqueNavElements boolean true If enabled (by default) and navigation elements' parameters passed as a string (like ".pagination") then Swiper will look for such elements through child elements first. Applies for pagination, prev/next buttons and scrollbar elements
effect string 'slide' Tranisition effect. Could be "slide", "fade", "cube", "coverflow" or "flip"
runCallbacksOnInit boolean true Fire [Transition/SlideChange][Start/End] events on swiper initialization. Such events will be fired on initialization in case of your initialSlide is not 0, or you use loop mode
watchOverflow boolean false When enabled Swiper will be disabled and hide navigation buttons on case there are not enough slides for sliding
on object Register event handlers
CSS Scroll Snap
cssMode boolean false

When enabled it will use modern CSS Scroll Snap API. It doesn't support all of Swiper's features, but potentially should bring a much better performance in simple configurations.

This is what is not supported when it is enabled:

  • All effects (Fade, Coverflow, Flip, Cube)
  • Zoom
  • Virtual Slides
  • speed parameter will have no effect
  • All transition start/end related events (use slideChange instead)
  • slidesPerGroup has limited support
  • centeredSlides is not supported
  • Changing slides with with anything except touch/swipe and mousewheel will happen without transition in browsers without scrollTo.behaviour = 'smooth' support (e.g. in desktop and iOS Safari)
  • simulateTouch doesn't have effect and "dragging" with mouse doesn't work
  • resistance doesn't have any effect
  • allowSlidePrev/Next
  • swipeHandler
  • freeMode and all relevant features
Slides grid
spaceBetween number 0

Distance between slides in px.

If you use "margin" css property to the elements which go into Swiper in which you pass "spaceBetween" into, navigation might not work property.
slidesPerView number or 'auto' 1

Number of slides per view (slides visible at the same time on slider's container).

If you use it with "auto" value and along with loop: true then you need to specify loopedSlides parameter with amount of slides to loop (duplicate)

slidesPerView: 'auto' is currently not compatible with multirow mode, when slidesPerColumn > 1
slidesPerColumn number 1 Number of slides per column, for multirow layout

slidesPerColumn > 1 is currently not compatible with loop mode (loop: true)
slidesPerColumnFill string 'column' Could be 'column' or 'row'. Defines how slides should fill rows, by column or by row. When 'column' it uses `flex-direction: column` layout which requires specified height on swiper-container.
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.
centeredSlidesBounds boolean false If true, then active slide will be centered without adding gaps at the beginning and end of slider. Required centeredSlides: true. Not intended to be used with loop or pagination
slidesOffsetBefore number 0 Add (in px) additional slide offset in the beginning of the container (before all slides)
slidesOffsetAfter number 0 Add (in px) additional slide offset in the end of the container (after all slides)
normalizeSlideIndex boolean true Normalize slide index.
centerInsufficientSlides boolean false When enabled it center slides if the amount of slides less than `slidesPerView`. Not intended to be used loop mode and slidesPerColumn
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
touchEventsTarget string 'wrapper' Target element to listen touch events on. Can be 'container' (to listen for touch events on swiper-container) or 'wrapper' (to listen for touch events on swiper-wrapper)
touchRatio number 1 Touch ratio
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
allowTouchMove boolean true If false, 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
touchStartPreventDefault boolean true If disabled, `touchstart` (`mousedown`) event won't be prevented
touchStartForcePreventDefault boolean false Force to always prevent default for `touchstart` (`mousedown`) event
touchMoveStopPropagation boolean false If enabled, then propagation of "touchmove" will be stopped
iOSEdgeSwipeDetection boolean false Enable to release Swiper events for swipe-to-go-back work in iOS UIWebView
iOSEdgeSwipeThreshold number 20 Area (in px) from left edge of the screen to release touch events for swipe-to-go-back in iOS UIWebView
touchReleaseOnEdges boolean false Enable to release touch events on slider edge position (beginning, end) to allow for further page scrolling
passiveListeners boolean true Passive event listeners will be used by default where possible to improve scrolling performance on mobile devices. But if you need to use `e.preventDefault` and you have conflict with it, then you should disable this parameter
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
Swiping / No swiping
preventInteractionOnTransition boolean false When enabled it won't allow to change slides by swiping or navigation/pagination buttons during transition
allowSlidePrev boolean true Set to false to disable swiping to previous slide direction (to left or top)
allowSlideNext boolean true Set to false to disable swiping to next slide direction (to right or bottom)
noSwiping boolean true Enable/disable swiping on elements matched to class specified in noSwipingClass
noSwipingClass string 'swiper-no-swiping' Specify noSwiping's' element css class
noSwipingSelector string Can be used instead of noSwipingClass to specify elements to disable swiping on. For example 'input' will disable swiping on all inputs
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
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
slideToClickedSlide boolean false Set to true and click on any slide will produce transition to this slide
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
freeModeMomentumVelocityRatio number 1 Higher value produces larger momentum velocity 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
freeModeMinimumVelocity number 0.02 Minimum touchmove-velocity required to trigger free mode momentum
freeModeSticky boolean false Set to true to enable snap to slides positions in free mode
Progress
watchSlidesProgress boolean false Enable this feature to calculate each slides progress
watchSlidesVisibility boolean false watchSlidesProgress should be enabled. Enable this option and slides that are in viewport will have additional visible class
Images
preloadImages boolean true When enabled Swiper will force to load all images
updateOnImagesReady boolean true When enabled Swiper will be reinitialized after all inner images (<img> tags) are loaded. Required preloadImages: true
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)

Also, because of nature of how the loop mode works, it will add duplicated slides. Such duplicated classes will have additional classes:

  • swiper-slide-duplicate - represents duplicated slide
  • swiper-slide-duplicate-active - represents slide duplicated to the currently active slide
  • swiper-slide-duplicate-next - represents slide duplicated to the slide next to active
  • swiper-slide-duplicate-prev - represents slide duplicated to the slide previous to active
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
loopFillGroupWithBlank boolean false Enable and loop mode will fill groups with insufficient number of slides with blank slides. Good to be used with slidesPerGroup parameter
Breakpoints
breakpoints object Allows to set different parameter for different responsive breakpoints (screen sizes). Not all parameters can be changed in breakpoints, only those which are not required different layout and logic, like slidesPerView, slidesPerGroup, spaceBetween, slidesPerColumn. Such parameters like loop and effect won't work. For example: 
 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
    }
  }
})
Observer
observer boolean false Set to true to enable Mutation Observer on Swiper and its elements. In this case Swiper will be updated (reinitialized) each time if you change its style (like hide/show) or modify its child elements (like adding/removing slides)
observeParents boolean false Set to true if you also need to watch Mutations for Swiper parent elements
observeSlideChildren boolean false Set to true if you also need to watch Mutations for Swiper slide children elements
Namespace
containerModifierClass string 'swiper-container-' The beginning of the modifier CSS class that can be added to swiper container depending on different parameters
slideClass string 'swiper-slide' CSS class name of slide
slideActiveClass string 'swiper-slide-active' CSS class name of currently active slide
slideDuplicateActiveClass string 'swiper-slide-duplicate-active' CSS class name of duplicated slide which represents the 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
slideDuplicateNextClass string 'swiper-slide-duplicate-next' CSS class name of duplicated slide which represents the slide next to active slide
slidePrevClass string 'swiper-slide-prev' CSS class name of slide which is right before currently active slide
slideDuplicatePrevClass string 'swiper-slide-duplicate-prev' CSS class name of duplicated slide which represents the slide previous to active slide
wrapperClass string 'swiper-wrapper' CSS class name of slides' wrapper

Default example

HTML structure

<div id="simple-swipe" class="swiper-container">
  <div class="swiper-wrapper">
    <div class="swiper-slide"><img src="path/to/demo-1.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-2.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-3.jpg" /></div>
  </div>
</div>

Script

var swiper = new Swiper('#simple-swipe');

With Navigation

HTML structure

<div id="navigation-swipe" class="swiper-container">
  <div class="swiper-wrapper">
    <div class="swiper-slide"><img src="path/to/demo-1.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-2.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-3.jpg" /></div>
  </div>
  <!-- Add Arrows -->
  <div class="swiper-button-next"></div>
  <div class="swiper-button-prev"></div>
</div>

Script

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

With Pagination

HTML structure

<div id="pagination-swipe" class="swiper-container">
  <div class="swiper-wrapper">
    <div class="swiper-slide"><img src="path/to/demo-1.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-2.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-3.jpg" /></div>
  </div>
  <!-- Add Pagination -->
  <div class="swiper-pagination"></div>
</div>

Script

var swiper = new Swiper('#pagination-swipe', {
   pagination: {
     el: '.swiper-pagination',
   },
});

Dynamic Pagination

HTML structure

<div id="dynamic-pagination" class="swiper-container">
  <div class="swiper-wrapper">
    <div class="swiper-slide"><img src="path/to/demo-1.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-2.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-3.jpg" /></div>
  </div>
  <!-- Add Pagination -->
  <div class="swiper-pagination"></div>
</div>

Script

var swiper = new Swiper('#dynamic-pagination', {
   pagination: {
     el: '.swiper-pagination',
     dynamicBullets: true,
   },
});

Progress Pagination

HTML structure

<div id="progress-pagination" class="swiper-container">
  <div class="swiper-wrapper">
    <div class="swiper-slide"><img src="path/to/demo-1.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-2.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-3.jpg" /></div>
  </div>
  <!-- Add Pagination -->
  <div class="swiper-pagination"></div>
  <!-- Add Arrows -->
  <div class="swiper-button-next"></div>
  <div class="swiper-button-prev"></div>
</div>

Script

var swiper = new Swiper('#progress-pagination', {
   pagination: {
     el: '.swiper-pagination',
     type: 'progressbar',
   },
   navigation: {
     nextEl: '.swiper-button-next',
     prevEl: '.swiper-button-prev',
   },
});

Fraction Pagination

HTML structure

<div id="fraction-pagination" class="swiper-container">
  <div class="swiper-wrapper">
    <div class="swiper-slide"><img src="path/to/demo-1.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-2.jpg" /></div>
    <div class="swiper-slide"><img src="path/to/demo-3.jpg" /></div>
  </div>
  <!-- Add Pagination -->
  <div class="swiper-pagination"></div>
  <!-- Add Arrows -->
  <div class="swiper-button-next"></div>
  <div class="swiper-button-prev"></div>
</div>

Script

var swiper = new Swiper('#fraction-pagination', {
  pagination: {
    el: '.swiper-pagination',
    type: 'fraction',
  },
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
});

You can explore many options within this slider as described below. Find out more

  • Custom Pagination
  • Scrollbar
  • Vertical Slider
  • Space Between Slides
  • Multiple Slides Per View
  • Auto Slides Per View / Carousel Mode
  • Centered Slides
  • Centered Slides + Auto Slides Per View
  • CSS Scroll Snap (CSS Mode)
  • Free Mode / No Fixed Positions
  • Scroll Container
  • Multi Row Slides Layout
  • Nested Swipers
  • Grab Cursor
  • Loop Mode / Infinite Loop
  • Loop Mode with Multiple Slides Per Group
  • Fade Effect
  • 3D Cube Effect
  • 3D Coverflow Effect
  • 3D Flip Effect
  • Keyboard Control (Open in new window)
  • Mousewheel Control
  • Autoplay
  • Dynamic Slides
  • Thumbs Gallery
  • Thumbs Gallery With Loop Mode
  • Hash Navigation (Open in new window)
  • History API (Open in new window)
  • RTL Layout
  • Parallax
  • Lazy Loading Images
  • Responsive Breakpoints (Open in new window)
  • Auto Height
  • Zoom
  • Virtual Slides
  • Slideable Navigation Drawer