Swiperv6.4.15
Most Modern Mobile Touch Slider

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>

Styles

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

CSS Styles

CSS styles for bundle version:

  • swiper-bundle.css - all Swiper styles including all modules styles (like Navigation, Pagination, etc.)
  • swiper-bundle.min.css - same as previous but minified

CSS styles for core version and modules:

  • swiper.min.css - only core Swiper styles
  • components/a11y/a11y.min.css - styles required for A11y module
  • components/controller/controller.min.css - styles required for Controller module
  • components/effect-coverflow/effect-coverflow.min.css - styles required for Coveflow Effect module
  • components/effect-cube/effect-cube.min.css - styles required for Cube Effect module
  • components/effect-fade/effect-fade.min.css - styles required for Fade Effect module
  • components/effect-flip/effect-flip.min.css - styles required for Flip Effect module
  • components/lazy/lazy.min.css - styles required for Lazy module
  • components/navigation/navigation.min.css - styles required for Navigation module
  • components/pagination/pagination.min.css - styles required for Pagination module
  • components/scrollbar/scrollbar.min.css - styles required for Scrollbar module
  • components/thumbs/thumbs.min.css - styles required for Thumbs module
  • components/zoom/zoom.min.css - styles required for Zoom module

Less Styles

Less styles are separate styles for core version and modules:

  • swiper.less - only core Swiper styles
  • components/a11y/a11y.less - styles required for A11y module
  • components/controller/controller.less - styles required for Controller module
  • components/effect-coverflow/effect-coverflow.less - styles required for Coveflow Effect module
  • components/effect-cube/effect-cube.less - styles required for Cube Effect module
  • components/effect-fade/effect-fade.less - styles required for Fade Effect module
  • components/effect-flip/effect-flip.less - styles required for Flip Effect module
  • components/lazy/lazy.less - styles required for Lazy module
  • components/navigation/navigation.less - styles required for Navigation module
  • components/pagination/pagination.less - styles required for Pagination module
  • components/scrollbar/scrollbar.less - styles required for Scrollbar module
  • components/thumbs/thumbs.less - styles required for Thumbs module
  • components/zoom/zoom.less - styles required for Zoom module

SCSS Styles

SCSS styles are also separate styles for core version and modules:

  • swiper.scss - only core Swiper styles
  • components/a11y/a11y.scss - styles required for A11y module
  • components/controller/controller.scss - styles required for Controller module
  • components/effect-coverflow/effect-coverflow.scss - styles required for Coveflow Effect module
  • components/effect-cube/effect-cube.scss - styles required for Cube Effect module
  • components/effect-fade/effect-fade.scss - styles required for Fade Effect module
  • components/effect-flip/effect-flip.scss - styles required for Flip Effect module
  • components/lazy/lazy.scss - styles required for Lazy module
  • components/navigation/navigation.scss - styles required for Navigation module
  • components/pagination/pagination.scss - styles required for Pagination module
  • components/scrollbar/scrollbar.scss - styles required for Scrollbar module
  • components/thumbs/thumbs.scss - styles required for Thumbs module
  • components/zoom/zoom.scss - styles required for Zoom module

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

  • swiperContainer - HTMLElement or string (with CSS Selector) of swiper container HTML element. Required.
  • parameters - object - object with Swiper parameters. Optional.
  • Method returns initialized Swiper instance

For example:

const swiper = 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:

const swiper = document.querySelector('.swiper-container').swiper;

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

Parameters

Let's look on list of all available parameters:

NameTypeDefaultDescription
allowSlideNextbooleantrue

Set to false to disable swiping to next slide direction (to right or bottom)

allowSlidePrevbooleantrue

Set to false to disable swiping to previous slide direction (to left or top)

allowTouchMovebooleantrue

If false, then the only way to switch the slide is use of external API functions like slidePrev or slideNext

autoHeightbooleanfalse

Set to true and slider wrapper will adapt its height to the height of the currently active slide

breakpointsobject

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

const 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
    }
  }
})
const swiper = new Swiper('.swiper-container', {
  slidesPerView: 1,
  spaceBetween: 10,
  // using "ratio" endpoints
  breakpoints: {
    '@0.75': {
      slidesPerView: 2,
      spaceBetween: 20,
    },
    '@1.00': {
      slidesPerView: 3,
      spaceBetween: 40,
    },
    '@1.50': {
      slidesPerView: 4,
      spaceBetween: 50,
    },
  }
});
centerInsufficientSlidesbooleanfalse

When enabled it center slides if the amount of slides less than slidesPerView. Not intended to be used loop mode and slidesPerColumn

centeredSlidesbooleanfalse

If true, then active slide will be centered, not always on the left side.

centeredSlidesBoundsbooleanfalse

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

containerModifierClassstring'swiper-container-'

The beginning of the modifier CSS class that can be added to swiper container depending on different parameters

cssModebooleanfalse

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 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
direction'horizontal' | 'vertical''horizontal'

Can be 'horizontal' or 'vertical' (for vertical slider).

edgeSwipeDetectionboolean | stringfalse

Enable to release Swiper events for swipe-back work in app. If set to 'prevent' then it will prevent system swipe-back navigation instead

edgeSwipeThresholdnumber20

Area (in px) from left edge of the screen to release touch events for swipe-back in app

effect'slide' | 'fade' | 'cube' | 'coverflow' | 'flip''slide'

Transition effect. Can be "slide", "fade", "cube", "coverflow" or "flip"

followFingerbooleantrue

If disabled, then slider will be animated only when you release it, it will not move while you hold your finger on it

freeModebooleanfalse

If enabled then slides will not have fixed positions

freeModeMinimumVelocitynumber0.02

Minimum touchmove-velocity required to trigger free mode momentum

freeModeMomentumbooleantrue

If enabled, then slide will keep moving for a while after you release it

freeModeMomentumBouncebooleantrue

Set to false if you want to disable momentum bounce in free mode

freeModeMomentumBounceRationumber1

Higher value produces larger momentum bounce effect

freeModeMomentumRationumber1

Higher value produces larger momentum distance after you release slider

freeModeMomentumVelocityRationumber1

Higher value produces larger momentum velocity after you release slider

freeModeStickybooleanfalse

Set to enabled to enable snap to slides positions in free mode

grabCursorbooleanfalse

This option may a little improve desktop usability. If true, user will see the "grab" cursor when hover on Swiper

heightnumber | nullnull

Swiper height (in px). Parameter allows to force Swiper height. Useful only if you initialize Swiper when it is hidden and in SSR and Test environments for correct Swiper initialization

Setting this parameter will make Swiper not responsive

initbooleantrue

Whether Swiper should be initialised automatically when you create an instance. If disabled, then you need to init it manually by calling swiper.init()

initialSlidenumber0

Index number of initial slide.

longSwipesbooleantrue

Set to false if you want to disable long swipes

longSwipesMsnumber300

Minimal duration (in ms) to trigger swipe to next/previous slide during long swipes

longSwipesRationumber0.5

Ratio to trigger swipe to next/previous slide during long swipes

loopbooleanfalse

Set to true to enable continuous loop mode

Because of nature of how the loop mode works, it will add duplicated slides. Such duplicated slides 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

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

loopAdditionalSlidesnumber0

Addition number of slides that will be cloned after creating of loop

loopFillGroupWithBlankbooleanfalse

Enable and loop mode will fill groups with insufficient number of slides with blank slides. Good to be used with slidesPerGroup parameter

loopPreventsSlidebooleantrue

When enabled it prevents Swiper slide prev/next transitions when transitions is already in progress (has effect when loop enabled)

loopedSlidesnumber | nullnull

If you use slidesPerView:'auto' with loop mode you should tell to Swiper how many slides it should loop (duplicate) using this parameter

nestedbooleanfalse

Set to true on Swiper for correct touch events interception. Use only on swipers that use same direction as the parent one

noSwipingbooleantrue

Enable/disable swiping on elements matched to class specified in noSwipingClass

noSwipingClassstring'swiper-no-swiping'

Specify noSwiping's element css class

noSwipingSelectorstring

Can be used instead of noSwipingClass to specify elements to disable swiping on. For example 'input' will disable swiping on all inputs

normalizeSlideIndexbooleantrue

Normalize slide index.

observeParentsbooleanfalse

Set to true if you also need to watch Mutations for Swiper parent elements

observeSlideChildrenbooleanfalse

Set to true if you also need to watch Mutations for Swiper slide children elements

observerbooleanfalse

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)

onobject

Register event handlers

passiveListenersbooleantrue

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

preloadImagesbooleantrue

When enabled Swiper will force to load all images

preventClicksbooleantrue

Set to true to prevent accidental unwanted clicks on links during swiping

preventClicksPropagationbooleantrue

Set to true to stop clicks event propagation on links during swiping

preventInteractionOnTransitionbooleanfalse

When enabled it won't allow to change slides by swiping or navigation/pagination buttons during transition

resistancebooleantrue

Set to false if you want to disable resistant bounds

resistanceRationumber0.85

This option allows you to control resistance ratio

roundLengthsbooleanfalse

Set to true to round values of slides width and height to prevent blurry texts on usual resolution screens (if you have such)

runCallbacksOnInitbooleantrue

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

setWrapperSizebooleanfalse

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

shortSwipesbooleantrue

Set to false if you want to disable short swipes

simulateTouchbooleantrue

If true, Swiper will accept mouse events like touch events (click and drag to change slides)

slideActiveClassstring'swiper-slide-active'

CSS class name of currently active slide

By changing classes you will also need to change Swiper's CSS to reflect changed classes

Not supported in Swiper Angular/React/Svelte/Vue components

slideBlankClassstring'swiper-slide-invisible-blank'

CSS class name of blank slide append to fill groups in loop mode when loopFillGroupWithBlank is also enabled

By changing classes you will also need to change Swiper's CSS to reflect changed classes

Not supported in Swiper Angular/React/Svelte/Vue

slideClassstring'swiper-slide'

CSS class name of slide

By changing classes you will also need to change Swiper's CSS to reflect changed classes

Not supported in Swiper Angular/React/Svelte/Vue components

slideDuplicateActiveClassstring'swiper-slide-duplicate-active'

CSS class name of duplicated slide which represents the currently active slide

By changing classes you will also need to change Swiper's CSS to reflect changed classes

Not supported in Swiper Angular/React/Svelte/Vue components

slideDuplicateClassstring'swiper-slide-duplicate'

CSS class name of slide duplicated by loop mode

By changing classes you will also need to change Swiper's CSS to reflect changed classes

Not supported in Swiper Angular/React/Svelte/Vue

slideDuplicateNextClassstring'swiper-slide-duplicate-next'

CSS class name of duplicated slide which represents the slide next to active slide

By changing classes you will also need to change Swiper's CSS to reflect changed classes

Not supported in Swiper Angular/React/Svelte/Vue

slideDuplicatePrevClassstring'swiper-slide-duplicate-prev'

CSS class name of duplicated slide which represents the slide previous to active slide

By changing classes you will also need to change Swiper's CSS to reflect changed classes

Not supported in Swiper Angular/React/Svelte/Vue

slideNextClassstring'swiper-slide-next'

CSS class name of slide which is right after currently active slide

By changing classes you will also need to change Swiper's CSS to reflect changed classes

Not supported in Swiper Angular/React/Svelte/Vue

slidePrevClassstring'swiper-slide-prev'

CSS class name of slide which is right before currently active slide

By changing classes you will also need to change Swiper's CSS to reflect changed classes

Not supported in Swiper Angular/React/Svelte/Vue

slideToClickedSlidebooleanfalse

Set to true and click on any slide will produce transition to this slide

slideVisibleClassstring'swiper-slide-visible'

CSS class name of currently visible slide

By changing classes you will also need to change Swiper's CSS to reflect changed classes

Not supported in Swiper Angular/React/Svelte/Vue

slidesOffsetAfternumber0

Add (in px) additional slide offset in the end of the container (after all slides)

slidesOffsetBeforenumber0

Add (in px) additional slide offset in the beginning of the container (before all slides)

slidesPerColumnnumber1

Number of slides per column, for multirow layout

slidesPerColumn > 1 is currently not compatible with loop mode (loop: true)

slidesPerColumnFill'row' | 'column''column'

Can be 'column' or 'row'. Defines how slides should fill rows, by column or by row

slidesPerGroupnumber1

Set numbers of slides to define and enable group sliding. Useful to use with slidesPerView > 1

slidesPerGroupSkipnumber0

The parameter works in the following way: If slidesPerGroupSkip equals 0 (default), no slides are excluded from grouping, and the resulting behaviour is the same as without this change.

If slidesPerGroupSkip is equal or greater than 1 the first X slides are treated as single groups, whereas all following slides are grouped by the slidesPerGroup value.

slidesPerViewnumber | '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

spaceBetweennumber0

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.

speednumber300

Duration of transition between slides (in ms)

swipeHandlerCSSSelector | HTMLElement | nullnull

String with CSS selector or HTML element of the container with pagination that will work as only available handler for swiping

thresholdnumber0

Threshold value in px. If "touch distance" will be lower than this value then swiper will not move

touchAnglenumber45

Allowable angle (in degrees) to trigger touch move

touchEventsTarget'container' | 'wrapper''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)

touchMoveStopPropagationbooleanfalse

If enabled, then propagation of "touchmove" will be stopped

touchRationumber1

Touch ratio

touchReleaseOnEdgesbooleanfalse

Enable to release touch events on slider edge position (beginning, end) to allow for further page scrolling

touchStartForcePreventDefaultbooleanfalse

Force to always prevent default for touchstart (mousedown) event

touchStartPreventDefaultbooleantrue

If disabled, touchstart (mousedown) event won't be prevented

uniqueNavElementsbooleantrue

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

updateOnImagesReadybooleantrue

When enabled Swiper will be reinitialized after all inner images ( tags) are loaded. Required preloadImages: true

updateOnWindowResizebooleantrue

Swiper will recalculate slides position on window resize (orientationchange)

urlstring | nullnull

Required for active slide detection when rendered on server-side and enabled history

userAgentstring | nullnull

userAgent string. Required for browser/device detection when rendered on server-side

virtualTranslatebooleanfalse

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

watchOverflowbooleanfalse

When enabled Swiper will be disabled and hide navigation buttons on case there are not enough slides for sliding.

watchSlidesProgressbooleanfalse

Enable this feature to calculate each slides progress

watchSlidesVisibilitybooleanfalse

watchSlidesProgress should be enabled. Enable this option and slides that are in viewport will have additional visible class

widthnumber | nullnull

Swiper width (in px). Parameter allows to force Swiper width. Useful only if you initialize Swiper when it is hidden and in SSR and Test environments for correct Swiper initialization

Setting this parameter will make Swiper not responsive

wrapperClassstring'swiper-wrapper'

CSS class name of slides' wrapper

By changing classes you will also need to change Swiper's CSS to reflect changed classes

Not supported in Swiper Angular/React/Svelte/Vue

onAny

Methods & Properties

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

Properties
swiper.$elDom7Array

Dom7 element with slider container HTML element. To get vanilla HTMLElement use swiper.el

swiper.$wrapperElDom7Array

Dom7 element with slider wrapper HTML element. To get vanilla HTMLElement use swiper.wrapperEl

swiper.activeIndexnumber

Index number of currently active slide

Note, that in loop mode active index value will be always shifted on a number of looped/duplicated slides

swiper.allowSlideNextboolean

Disable / enable ability to slide to the next slides by assigning false / true to this property

swiper.allowSlidePrevboolean

Disable / enable ability to slide to the previous slides by assigning false / true to this property

swiper.allowTouchMoveboolean

Disable / enable ability move slider by grabbing it with mouse or by touching it with finger (on touch screens) by assigning false / true to this property

swiper.animatingboolean

true if swiper is in transition

swiper.clickedIndexnumber

Index number of last clicked slide

swiper.clickedSlideHTMLElement

Link to last clicked slide (HTMLElement)

swiper.elHTMLElement

Slider container HTML element

swiper.heightnumber

Height of container

swiper.isBeginningboolean

true if slider on most "left"/"top" position

swiper.isEndboolean

true if slider on most "right"/"bottom" position

swiper.paramsSwiperOptions

Object with passed initialization parameters

swiper.previousIndexnumber

Index number of previously active slide

swiper.progressnumber

Current progress of wrapper translate (from 0 to 1)

swiper.realIndexnumber

Index number of currently active slide considering duplicated slides in loop mode

swiper.slidesDom7Array

Dom7 array-like collection of slides HTML elements. To get specific slide HTMLElement use swiper.slides[1]

swiper.touchesobject

Object with the following touch event properties:

  • swiper.touches.startX
  • swiper.touches.startY
  • swiper.touches.currentX
  • swiper.touches.currentY
  • swiper.touches.diff
swiper.translatenumber

Current value of wrapper translate

swiper.widthnumber

Width of container

swiper.wrapperElHTMLElement

Wrapper HTML element

swiper.defaultsSwiperOptions

Swiper default options

swiper.extendedDefaultsSwiperOptions

Object with global Swiper exntended options

Methods
swiper.addSlide(index, slides)

Add new slides to the required index. slides could be HTMLElement or HTML string with new slide or array with such slides, for example:

addSlide(1, '<div className="swiper-slide">Slide 10"</div>')

addSlide(1, [
 '<div className="swiper-slide">Slide 10"</div>',
 '<div className="swiper-slide">Slide 11"</div>'
]);
swiper.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:

appendSlide('<div className="swiper-slide">Slide 10"</div>')

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

Attach all events listeners again

swiper.changeDirection(direction, needUpdate)

Changes slider direction from horizontal to vertical and back.

  • direction - 'horizontal' | 'vertical' - New direction. If not specified, then will automatically changed to opposite direction
  • needUpdate - boolean - Will call swiper.update(). Default true
swiper.destroy(deleteInstance, cleanStyles)

Destroy slider instance and detach all events listeners

  • deleteInstance - boolean - Set it to false (by default it is true) to not to delete Swiper instance
  • cleanStyles - boolean - Set it to true (by default it is true) and all custom styles will be removed from slides, wrapper and container. Useful if you need to destroy Swiper and to init again with new options or in different direction
swiper.detachEvents()

Detach all events listeners

swiper.emit(event, args)

Fire event on instance

swiper.getBreakpoint(breakpoints)
swiper.getTranslate()

Get current value of swiper wrapper css3 transform translate

swiper.init()

Initialize slider

swiper.off(event, handler)

Remove event handler

swiper.offAny(handler)

Remove event listener that will be fired on all events

swiper.on(event, handler)

Add event handler

swiper.onAny(handler)

Add event listener that will be fired on all events

swiper.once(event, handler)

Add event handler that will be removed after it was fired

swiper.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:

prependSlide('<div className="swiper-slide">Slide 0"</div>')

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

Remove all slides

swiper.removeSlide(slideIndex)

Remove selected slides. slideIndex could be a number with slide index to remove or array with indexes.

removeSlide(0); // remove first slide
removeSlide([0, 1]); // remove first and second slides
removeAllSlides();    // Remove all slides
swiper.setGrabCursor()

Set grab cursor

swiper.setTranslate(translate)

Set custom css3 transform's translate value for swiper wrapper

swiper.slideNext(speed, runCallbacks)

Run transition to next slide.

  • speed - number - Transition duration (in ms).
  • runCallbacks - boolean - Set it to false (by default it is true) and transition will not produce transition events.
swiper.slidePrev(speed, runCallbacks)

Run transition to previous slide.

  • speed - number - Transition duration (in ms).
  • runCallbacks - boolean - Set it to false (by default it is true) and transition will not produce transition events.
swiper.slideReset(speed, runCallbacks)

Reset swiper position to currently active slide for the duration equal to 'speed' parameter.

  • speed - number - Transition duration (in ms).
  • runCallbacks - boolean - Set it to false (by default it is true) and transition will not produce transition events.
swiper.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).
  • runCallbacks - boolean - Set it to false (by default it is true) and transition will not produce transition events.
swiper.slideToClosest(speed, runCallbacks)

Reset swiper position to closest slide/snap point for the duration equal to 'speed' parameter.

  • speed - number - Transition duration (in ms).
  • runCallbacks - boolean - Set it to false (by default it is true) and transition will not produce transition events.
swiper.slideToLoop(index, speed, runCallbacks)

Does the same as .slideTo but for the case when used with enabled loop. So this method will slide to slides with realIndex matching to passed index

  • index - number - Index number of slide.
  • speed - number - Transition duration (in ms).
  • runCallbacks - boolean - Set it to false (by default it is true) and transition will not produce transition events.
swiper.translateTo(translate, speed, runCallbacks, translateBounds)

Animate custom css3 transform's translate value for swiper wrapper

  • translate - number - Translate value (in px)
  • speed - number - Transition duration (in ms)
  • runCallbacks - boolean - Set it to false (by default it is true) and transition will not produce transition events
  • translateBounds - boolean - Set it to false (by default it is true) and transition value can extend beyond min and max translate
swiper.unsetGrabCursor()

Unset grab cursor

swiper.update()

You should call it after you add/remove slides manually, or after you hide/show it, or do any custom DOM modifications with Swiper This method also includes subcall of the following methods which you can use separately:

swiper.updateAutoHeight(speed)

Force swiper to update its height (when autoHeight enabled) for the duration equal to 'speed' parameter

  • speed - number - Transition duration (in ms).
swiper.updateProgress()

recalculate swiper progress

swiper.updateSize()

recalculate size of swiper container

swiper.updateSlides()

recalculate number of slides and their offsets. Useful after you add/remove slides with JavaScript

swiper.updateSlidesClasses()

update active/prev/next classes on slides and bullets

swiper.extendDefaults(options)

Extend global Swiper defaults

swiper.use(modules)

Installs modules on Swiper in runtime.

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:

    const swiper = new Swiper('.swiper-container', {
      // ...
      on: {
        init: function () {
          console.log('swiper initialized');
        },
      },
    });
    
  2. Using on method after swiper initialization.

    const swiper = new Swiper('.swiper-container', {
      // ...
    });
    swiper.on('slideChange', function () {
      console.log('slide changed');
    });
    
Please note, that this keyword within event handler always points to Swiper instance
NameArgumentsDescription
activeIndexChange(swiper)

Event will fired on active index change

afterInit(swiper)

Event will fired right after initialization

beforeDestroy(swiper)

Event will be fired right before Swiper destroyed

beforeInit(swiper)

Event will fired right before initialization

beforeLoopFix(swiper)

Event will be fired right before "loop fix"

beforeResize(swiper)

Event will fired before resize handler

beforeSlideChangeStart(swiper)

Event will fired before slide change transition start

beforeTransitionStart(swiper, speed, internal)

Event will fired before transition start

breakpoint(swiper, breakpointParams)

Event will be fired on breakpoint change

changeDirection(swiper)

Event will fired on direction change

click(swiper, event)

Event will be fired when user click/tap on Swiper. Receives touchend event as an arguments.

destroy(swiper)

Event will be fired on swiper destroy

doubleClick(swiper, event)

Event will be fired when user double click/tap on Swiper

doubleTap(swiper, event)

Event will be fired when user double tap on Swiper's container. Receives touchend event as an arguments

fromEdge(swiper)

Event will be fired when Swiper goes from beginning or end position

imagesReady(swiper)

Event will be fired right after all inner images are loaded. updateOnImagesReady should be also enabled

init(swiper)

Fired right after Swiper initialization.

Note that with swiper.on('init') syntax it will work only in case you set init: false parameter.

const swiper = new Swiper('.swiper-container', {
  init: false,
  // other parameters
});
swiper.on('init', function() {
 // do something
});
// init Swiper
swiper.init();
// Otherwise use it as the parameter:
const swiper = new Swiper('.swiper-container', {
  // other parameters
  on: {
    init: function () {
      // do something
    },
  }
});
loopFix(swiper)

Event will be fired after "loop fix"

momentumBounce(swiper)

Event will be fired on momentum bounce

observerUpdate(swiper)

Event will be fired if observer is enabled and it detects DOM mutations

orientationchange(swiper)

Event will be fired on orientation change (e.g. landscape -> portrait)

progress(swiper, progress)

Event will be fired when Swiper progress is changed, as an arguments it receives progress that is always from 0 to 1

reachBeginning(swiper)

Event will be fired when Swiper reach its beginning (initial position)

reachEnd(swiper)

Event will be fired when Swiper reach last slide

realIndexChange(swiper)

Event will fired on real index change

resize(swiper)

Event will be fired on window resize right before swiper's onresize manipulation

setTransition(swiper, transition)

Event will be fired everytime when swiper starts animation. Receives current transition duration (in ms) as an arguments

setTranslate(swiper, translate)

Event will be fired when swiper's wrapper change its position. Receives current translate value as an arguments

slideChange(swiper)

Event will be fired when currently active slide is changed

slideChangeTransitionEnd(swiper)

Event will be fired after animation to other slide (next or previous).

slideChangeTransitionStart(swiper)

Event will be fired in the beginning of animation to other slide (next or previous).

slideNextTransitionEnd(swiper)

Same as "slideChangeTransitionEnd" but for "forward" direction only

slideNextTransitionStart(swiper)

Same as "slideChangeTransitionStart" but for "forward" direction only

slidePrevTransitionEnd(swiper)

Same as "slideChangeTransitionEnd" but for "backward" direction only

slidePrevTransitionStart(swiper)

Same as "slideChangeTransitionStart" but for "backward" direction only

slideResetTransitionEnd(swiper)

Event will be fired in the end of animation of resetting slide to current one

slideResetTransitionStart(swiper)

Event will be fired in the beginning of animation of resetting slide to current one

sliderFirstMove(swiper, event)

Event will be fired with first touch/drag move

sliderMove(swiper, event)

Event will be fired when user touch and move finger over Swiper and move it. Receives touchmove event as an arguments.

slidesGridLengthChange(swiper)

Event will be fired when slides grid has changed

slidesLengthChange(swiper)

Event will be fired when number of slides has changed

snapGridLengthChange(swiper)

Event will be fired when snap grid has changed

snapIndexChange(swiper)

Event will fired on snap index change

tap(swiper, event)

Event will be fired when user click/tap on Swiper. Receives touchend event as an arguments.

toEdge(swiper)

Event will be fired when Swiper goes to beginning or end position

touchEnd(swiper, event)

Event will be fired when user release Swiper. Receives touchend event as an arguments.

touchMove(swiper, event)

Event will be fired when user touch and move finger over Swiper. Receives touchmove event as an arguments.

touchMoveOpposite(swiper, event)

Event will be fired when user touch and move finger over Swiper in direction opposite to direction parameter. Receives touchmove event as an arguments.

touchStart(swiper, event)

Event will be fired when user touch Swiper. Receives touchstart event as an arguments.

transitionEnd(swiper)

Event will be fired after transition.

transitionStart(swiper)

Event will be fired in the beginning of transition.

update(swiper)

Event will be fired after swiper.update() call

Modules

NameTypeDefaultDescription
navigationNavigationOptions | boolean

Object with navigation parameters

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

CSS class name added to navigation button when it becomes disabled

hiddenClassstring'swiper-button-hidden'

CSS class name added to navigation button when it becomes hidden

hideOnClickbooleanfalse

Toggle navigation buttons visibility after click on Slider's container

lockClassstring'swiper-button-lock'

CSS class name added to navigation button when it is disabled

nextElCSSSelector | HTMLElement | nullnull

String with CSS selector or HTML element of the element that will work like "next" button after click on it

prevElCSSSelector | HTMLElement | nullnull

String with CSS selector or HTML element of the element that will work like "prev" button after click on it

}
Properties
swiper.navigation.nextElHTMLElement

HTMLElement of "next" navigation button

swiper.navigation.prevElHTMLElement

HTMLElement of "previous" navigation button

Methods
swiper.navigation.destroy()

Destroy navigation

swiper.navigation.init()

Initialize navigation

swiper.navigation.update()

Update navigation buttons state (enabled/disabled)

NameArgumentsDescription
navigationHide(swiper)

Event will be fired on navigation hide

navigationShow(swiper)

Event will be fired on navigation show

Pagination

Pagination Parameters

NameTypeDefaultDescription
paginationPaginationOptions | boolean

Object with navigation parameters

const swiper = new Swiper('.swiper-container', {
  pagination: {
    el: '.swiper-pagination',
    type: 'bullets',
  },
});
{
bulletActiveClassstring'swiper-pagination-bullet-active'

CSS class name of currently active pagination bullet

bulletClassstring'swiper-pagination-bullet'

CSS class name of single pagination bullet

bulletElementstring'span'

Defines which HTML tag will be used to represent single pagination bullet. Only for 'bullets' pagination type.

clickablebooleanfalse

If true then clicking on pagination button will cause transition to appropriate slide. Only for bullets pagination type

clickableClassstring'swiper-pagination-clickable'

CSS class name set to pagination when it is clickable

currentClassstring'swiper-pagination-current'

CSS class name of the element with currently active index in "fraction" pagination

dynamicBulletsbooleanfalse

Good to enable if you use bullets pagination with a lot of slides. So it will keep only few bullets visible at the same time.

dynamicMainBulletsnumber1

The number of main bullets visible when dynamicBullets enabled.

elCSSSelector | HTMLElement | nullnull

String with CSS selector or HTML element of the container with pagination

formatFractionCurrentfunction(number)

format fraction pagination current number. Function receives current number, and you need to return formatted value

formatFractionTotalfunction(number)

format fraction pagination total number. Function receives total number, and you need to return formatted value

hiddenClassstring'swiper-pagination-hidden'

CSS class name of pagination when it becomes inactive

hideOnClickbooleantrue

Toggle (hide/show) pagination container visibility after click on Slider's container

lockClassstring'swiper-pagination-lock'

CSS class name set to pagination when it is disabled

modifierClassstring'swiper-pagination-'

The beginning of the modifier CSS class name that will be added to pagination depending on parameters

progressbarFillClassstring'swiper-pagination-progressbar-fill'

CSS class name of pagination progressbar fill element

progressbarOppositebooleanfalse

Makes pagination progressbar opposite to Swiper's direction parameter, means vertical progressbar for horizontal swiper direction and horizontal progressbar for vertical swiper direction

progressbarOppositeClassstring'swiper-pagination-progressbar-opposite'

CSS class name of pagination progressbar opposite

renderBulletfunction(index, className)null

This parameter allows totally customize pagination bullets, you need to pass here a function that accepts index number of pagination bullet and required element class name (className). Only for 'bullets' pagination type

const swiper = new Swiper('.swiper-container', {
  //...
  renderBullet: function (index, className) {
    return '<span className="' + className + '">' + (index + 1) + '</span>';
  }
});
renderCustomfunction(swiper, current, total)null

This parameter is required for 'custom' pagination type where you have to specify how it should be rendered.

const swiper = new Swiper('.swiper-container', {
  //...
  renderCustom: function (swiper, current, total) {
    return current + ' of ' + total;
  }
});
renderFractionfunction(currentClass, totalClass)null

This parameter allows to customize "fraction" pagination html. Only for 'fraction' pagination type

const swiper = new Swiper('.swiper-container', {
  //...
  renderFraction: function (currentClass, totalClass) {
      return '<span className="' + currentClass + '"></span>' +
              ' of ' +
              '<span className="' + totalClass + '"></span>';
  }
});
renderProgressbarfunction(progressbarFillClass)null

This parameter allows to customize "progress" pagination. Only for 'progress' pagination type

const swiper = new Swiper('.swiper-container', {
  //...
  renderProgressbar: function (progressbarFillClass) {
      return '<span className="' + progressbarFillClass + '"></span>';
  }
});
totalClassstring'swiper-pagination-total'

CSS class name of the element with total number of "snaps" in "fraction" pagination

type'bullets' | 'fraction' | 'progressbar' | 'custom''bullets'

String with type of pagination. Can be "bullets", "fraction", "progressbar" or "custom"

}

Pagination Methods

Properties
swiper.pagination.bullets

Dom7 array-like collection of pagination bullets HTML elements. To get specific slide HTMLElement use swiper.pagination.bullets[1].

swiper.pagination.elHTMLElement

HTMLElement of pagination container element

Methods
swiper.pagination.destroy()

Destroy pagination

swiper.pagination.init()

Initialize pagination

swiper.pagination.render()

Render pagination layout

swiper.pagination.update()

Update pagination state (enabled/disabled/active)

Pagination Events

NameArgumentsDescription
paginationHide(swiper)

Event will be fired on pagination hide

paginationRender(swiper, paginationEl)

Event will be fired after pagination rendered

paginationShow(swiper)

Event will be fired on pagination show

paginationUpdate(swiper, paginationEl)

Event will be fired when pagination updated

Scrollbar

Scrollbar Parameters

NameTypeDefaultDescription
scrollbarScrollbarOptions | boolean

Object with scrollbar parameters

const swiper = new Swiper('.swiper-container', {
  scrollbar: {
    el: '.swiper-scrollbar',
    draggable: true,
  },
});
{
dragClassstring'swiper-scrollbar-drag'
Scrollbar draggable element CSS class
dragSize'auto' | number'auto'

Size of scrollbar draggable element in px

draggablebooleantrue

Set to true to enable make scrollbar draggable that allows you to control slider position

elCSSSelector | HTMLElement | nullnull

String with CSS selector or HTML element of the container with scrollbar.

hidebooleantrue

Hide scrollbar automatically after user interaction

lockClassstring'swiper-scrollbar-lock'

Scrollbar element additional CSS class when it is disabled

snapOnReleasebooleanfalse

Set to true to snap slider position to slides when you release scrollbar

}

Scrollbar Methods

Properties
swiper.scrollbar.dragElHTMLElement

HTMLElement of Scrollbar draggable handler element

swiper.scrollbar.elHTMLElement

HTMLElement of Scrollbar container element

Methods
swiper.scrollbar.destroy()

Destroy scrollbar

swiper.scrollbar.init()

Initialize scrollbar

swiper.scrollbar.setTranslate()

Updates scrollbar translate

swiper.scrollbar.updateSize()

Updates scrollbar track and handler sizes

Scrollbar Events

NameArgumentsDescription
scrollbarDragEnd(swiper, event)

Event will be fired on draggable scrollbar drag end

scrollbarDragMove(swiper, event)

Event will be fired on draggable scrollbar drag move

scrollbarDragStart(swiper, event)

Event will be fired on draggable scrollbar drag start

Autoplay

Autoplay Parameters

NameTypeDefaultDescription
autoplayAutoplayOptions | boolean

Object with autoplay parameters or boolean true to enable with default settings

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

Delay between transitions (in ms). If this parameter is not specified, auto play will be disabled

If you need to specify different delay for specific slides you can do it by usingdata-swiper-autoplay (in ms) attribute on slide.

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

Set to false and autoplay will not be disabled after user interactions (swipes), it will be restarted every time after interaction

reverseDirectionbooleanfalse

Enables autoplay in reverse direction

stopOnLastSlidebooleanfalse

Enable this parameter and autoplay will be stopped when it reaches last slide (has no effect in loop mode)

waitForTransitionbooleantrue

When enabled autoplay will wait for wrapper transition to continue. Can be disabled in case of using Virtual Translate when your slider may not have transition

}

Autoplay Methods

Properties
swiper.autoplay.runningboolean

Whether autoplay enabled and running

Methods
swiper.autoplay.start()

Start autoplay

swiper.autoplay.stop()

Stop autoplay

Autoplay Events

NameArgumentsDescription
autoplay(swiper)

Event will be fired when slide changed with autoplay

autoplayStart(swiper)

Event will be fired in when autoplay started

autoplayStop(swiper)

Event will be fired when autoplay stopped

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

NameTypeDefaultDescription
parallaxParallaxOptions | boolean

Object with parallax parameters

const swiper = new Swiper('.swiper-container', {
  parallax: true,
});
{
enabledbooleanfalse

Enable, if you want to use "parallaxed" elements inside of slider

}

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:

const swiper = new Swiper('.swiper-container', {
  // Disable preloading of all images
  preloadImages: false,
  // Enable lazy loading
  lazy: true,
});
If you use slidesPerView: 'auto' or slidesPerView > 1, then you should also enable watchSlidesVisibility and Swiper will load images in currently visible slides

Lazy Loading Parameters

NameTypeDefaultDescription
lazyLazyOptions | boolean

Enables images lazy loading. Object with lazy loading parameters or boolean true to enable with default settings

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

Enables to check is the Swiper in view before lazy loading images on initial slides

elementClassstring'swiper-lazy'

CSS class name of lazy element

loadOnTransitionStartbooleanfalse

By default, Swiper will load lazy images after transition to this slide, so you may enable this parameter if you need it to start loading of new image in the beginning of transition

loadPrevNextbooleanfalse

Set to true to enable lazy loading for the closest slides images (for previous and next slide images)

loadPrevNextAmountnumber1

Amount of next/prev slides to preload lazy images in. Can't be less than slidesPerView

loadedClassstring'swiper-lazy-loaded'

CSS class name of lazy loaded element

loadingClassstring'swiper-lazy-loading'

CSS class name of lazy loading element

preloaderClassstring'swiper-lazy-preloader'

CSS class name of lazy preloader

scrollingElementCSSSelector | null | Dom7Array | HTMLElement

Element to check scrolling on for checkInView. Defaults to window

}

Lazy Loading Methods

Methods
swiper.lazy.load()

Load/update lazy images based on current slider state (position)

swiper.lazy.loadInSlide(index)

Force to load lazy images in slide by specified index

Lazy Loading Events

NameArgumentsDescription
lazyImageLoad(swiper, slideEl, imageEl)

Event will be fired in the beginning of lazy loading of image

lazyImageReady(swiper, slideEl, imageEl)

Event will be fired when lazy loading image will be loaded

Fade Effect

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

Note that crossFade should be set to true in order to avoid seeing content behind or underneath.

Fade Effect Parameters

NameTypeDefaultDescription
fadeEffectFadeEffectOptions

Object with Fade-effect parameters

const swiper = new Swiper('.swiper-container', {
  effect: 'fade',
  fadeEffect: {
    crossFade: true
  },
});
{
crossFadebooleanfalse

Enables slides cross fade

}

Coverflow Effect

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

Coverflow Effect Parameters

NameTypeDefaultDescription
coverflowEffectCoverflowEffectOptions

Object with Coverflow-effect parameters.

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

Depth offset in px (slides translate in Z axis)

modifiernumber1

Effect multiplier

rotatenumber50

Slide rotate in degrees

slideShadowsbooleantrue

Enables slides shadows

stretchnumber0

Stretch space between slides (in px)

}

Flip Effect

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

Flip Effect Parameters

NameTypeDefaultDescription
flipEffectFlipEffectOptions

Object with Flip-effect parameters

const swiper = new Swiper('.swiper-container', {
  flipEffect: {
    slideShadows: false,
  },
});
{
limitRotationbooleantrue

Limit edge slides rotation

slideShadowsbooleantrue

Enables slides shadows

}

Cube Effect

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

Cube Effect Parameters

NameTypeDefaultDescription
cubeEffectCubeEffectOptions

Object with Cube-effect parameters

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

Enables main slider shadow

shadowOffsetnumber20

Main shadow offset in px

shadowScalenumber0.94

Main shadow scale ratio

slideShadowsbooleantrue

Enables slides shadows

}

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

NameTypeDefaultDescription
thumbsThumbsOptions

Object with thumbs component parameters

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

Allows to set on which thumbs active slide from edge it should automatically move scroll thumbs. For example, if set to 1 and last visible thumb will be activated (1 from edge) it will auto scroll thumbs

multipleActiveThumbsbooleantrue

When enabled multiple thumbnail slides may get activated

slideThumbActiveClassstring'swiper-slide-thumb-active'

Additional class that will be added to activated thumbs swiper slide

swiperSwiper | nullnull

Swiper instance of swiper used as thumbs or object with Swiper parameters to initialize thumbs swiper

thumbsContainerClassstring'swiper-container-thumbs'

Additional class that will be added to thumbs swiper-container

}

Thumbs Methods

Properties
swiper.thumbs.swiperSwiper

Swiper instance of thumbs swiper

Methods
swiper.thumbs.init()

Initialize thumbs

swiper.thumbs.update(initial)

Update thumbs

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>
    </div>
    
  • You can override maxRatio parameter for specific slides by using data-swiper-zoom attribute on zoom container.

Zoom Parameters

NameTypeDefaultDescription
zoomZoomOptions | boolean

Enables zooming functionality. Object with zoom parameters or boolean true to enable with default settings

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

CSS class name of zoom container

maxRationumber3

Maximum image zoom multiplier

minRationumber1

Minimal image zoom multiplier

togglebooleantrue

Enable/disable zoom-in by slide's double tap

zoomedSlideClassstring'swiper-slide-zoomed'

CSS class name of zoomed in container

}

Zoom Methods

Properties
swiper.zoom.enabledboolean

Whether the zoom module is enabled

swiper.zoom.scalenumber

Current image scale ratio

Methods
swiper.zoom.disable()

Disable zoom module

swiper.zoom.enable()

Enable zoom module

swiper.zoom.in()

Zoom in image of the currently active slide

swiper.zoom.out()

Zoom out image of the currently active slide

swiper.zoom.toggle()

Toggle image zoom of the currently active slide

Zoom Events

NameArgumentsDescription
zoomChange(swiper, scale, imageEl, slideEl)

Event will be fired on zoom change

Keyboard Control

Keyboard Control Parameters

NameTypeDefaultDescription
keyboardKeyboardOptions | boolean

Enables navigation through slides using keyboard. Object with keyboard parameters or boolean true to enable with default settings

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

Set to true to enable keyboard contro

onlyInViewportbooleantrue

When enabled it will control sliders that are currently in viewport

pageUpDownbooleantrue

When enabled it will enable keyboard navigation by Page Up and Page Down keys

}

Keyboard Control Methods

Properties
swiper.keyboard.enabledboolean

Whether the keyboard control is enabled

Methods
swiper.keyboard.disable()

Disable keyboard control

swiper.keyboard.enable()

Enable keyboard control

Keyboard Events

NameArgumentsDescription
keyPress(swiper, keyCode)

Event will be fired on key press

Mousewheel Control

Mousewheel Control Parameters

NameTypeDefaultDescription
mousewheelMousewheelOptions | boolean

Enables navigation through slides using mouse wheel. Object with mousewheel parameters or boolean true to enable with default settings

const swiper = new Swiper('.swiper-container', {
  mousewheel: {
    invert: true,
  },
});
{
eventsTarget'container' | 'wrapper' | CSSSelector | HTMLElement'container'

String with CSS selector or HTML element of the container accepting mousewheel events. By default it is swiper-container

forceToAxisbooleanfalse

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.

invertbooleanfalse

Set to true to invert sliding direction

releaseOnEdgesbooleanfalse

Set to true and swiper will release mousewheel event and allow page scrolling when swiper is on edge positions (in the beginning or in the end)

sensitivitynumber1

Multiplier of mousewheel data, allows to tweak mouse wheel sensitivity

thresholdDeltanumber | nullnull

Minimum mousewheel scroll delta to trigger swiper slide change

thresholdTimenumber | nullnull

Minimum mousewheel scroll time delta (in ms) to trigger swiper slide change

}

Mousewheel Control Methods

Properties
swiper.mousewheel.enabledboolean

Whether the mousewheel control is enabled

Methods
swiper.mousewheel.disable()

Disable mousewheel control

swiper.mousewheel.enable()

Enable mousewheel control

Mousewheel Events

NameArgumentsDescription
scroll(swiper, event)

Event will be fired on mousewheel scroll

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.

Note that according to Virtual Slides realization it doesn't work with loop mode, slidesPerColumn more than 1 and slidesPerView: 'auto'

Virtual Slides Parameters

NameTypeDefaultDescription
virtualVirtualOptions | boolean

Enables virtual slides functionality. Object with virtual slides parameters or boolean true to enable with default settings.

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

Increases amount of pre-rendered slides after active slide

addSlidesBeforenumber0

Increases amount of pre-rendered slides before active slide

cachebooleantrue

Enables DOM cache of rendering slides html elements. Once they are rendered they will be saved to cache and reused from it.

renderExternalfunction(data)null

Function for external rendering (e.g. using some other library to handle DOM manipulations and state like React.js or Vue.js). As an argument it accepts data object with the following properties:

  • offset - slides left/top offset in px
  • from - index of first slide required to be rendered
  • to - index of last slide required to be rendered
  • slides - array with slide items to be rendered
renderExternalUpdatebooleantrue

When enabled (by default) it will update Swiper layout right after renderExternal called. Useful to disable and update swiper manually when used with render libraries that renders asynchronously

renderSlidefunction(slide, index)null

Function to render slide. As an argument it accepts current slide item for slides array and index number of the current slide. Function must return an outter HTML of the swiper slide.

slides[]

Array with slides

}

Virtual Slides Methods

Properties
swiper.virtual.cacheobject

Object with cached slides HTML elements

swiper.virtual.fromnumber

Index of first rendered slide

swiper.virtual.slides

Array with slide items passed by virtual.slides parameter

swiper.virtual.tonumber

Index of last rendered slide

Methods
swiper.virtual.appendSlide(slide)

Append slide. slides can be a single slide item or array with such slides.

swiper.virtual.prependSlide(slide)

Prepend slide. slides can be a single slide item or array with such slides.

swiper.virtual.removeAllSlides()

Remove all slides

swiper.virtual.removeSlide(slideIndexes)

Remove specific slide or slides. slideIndexes can be a number with slide index to remove or array with indexes.

swiper.virtual.update(force)

Update virutal slides state

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="slideStyles"
      >
        {{slide}}
      </div>
    </div>
  </div>
  <!-- ... -->
</template>
<script>
  import Swiper from 'swiper/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: [],
        },
      };
    },
    computed: {
      slideStyles() {
        return `left: ${this.virtualData.offset}px;`;
      },
    },
    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/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>
const swiper = new Swiper('.swiper-container', {
  //enable hash navigation
  hashNavigation: true,
});

Hash Navigation Parameters

NameTypeDefaultDescription
hashNavigationHashNavigationOptions | boolean

Enables hash url navigation to for slides. Object with hash navigation parameters or boolean true to enable with default settings

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

Works in addition to hashnav to replace current url state with the new one instead of adding it to history

watchStatebooleanfalse

Set to true to enable also navigation through slides (when hashnav is enabled) by browser history or by setting directly hash on document location

}

Hash Navigation Events

NameArgumentsDescription
hashChange(swiper)

Event will be fired on window hash change

hashSet(swiper)

Event will be fired when swiper updates the hash

History Navigation

History Navigation Parameters

NameTypeDefaultDescription
historyHistoryOptions | boolean

Enables history push state where every slide will have its own url. In this parameter you have to specify main slides url like "slides" and specify every slide url using data-history attribute.

Object with history navigation parameters or boolean true to enable with default settings

const swiper = new Swiper('.swiper-container', {
  history: {
    replaceState: true,
  },
});
<!-- will produce "slides/slide1" url in browser history -->
<div class="swiper-slide" data-history="slide1"></div>
{
keystring'slides'

Url key for slides

replaceStatebooleanfalse

Works in addition to hashnav or history to replace current url state with the new one instead of adding it to history

}

Controller

Controller Parameters

NameTypeDefaultDescription
controllerControllerOptions

Object with controller parameters or boolean true to enable with default settings

const swiper = new Swiper('.swiper-container', {
  controller: {
    inverse: true,
  },
});
{
by'slide' | 'container''slide'

Defines a way how to control another slider: slide by slide (with respect to other slider's grid) or depending on all slides/container (depending on total slider percentage).

controlSwiper

Pass here another Swiper instance or array with Swiper instances that should be controlled by this Swiper

inversebooleanfalse

Set to true and controlling will be in inverse direction

}

Controller Methods

Properties
swiper.controller.controlSwiper

Pass here another Swiper instance or array with Swiper instances that should be controlled by this Swiper

Accessibility (a11y)

Accessibility Parameters

NameTypeDefaultDescription
a11yA11yOptions

Object with a11y parameters or boolean true to enable with default settings.

const swiper = new Swiper('.swiper-container', {
  a11y: {
    prevSlideMessage: 'Previous slide',
    nextSlideMessage: 'Next slide',
  },
});
{
containerMessagestring | nullnull

Message for screen readers for outer swiper container

containerRoleDescriptionMessagestring | nullnull

Message for screen readers describing the role of outer swiper container

enabledbooleantrue

Enables A11y

firstSlideMessagestring'This is the first slide'

Message for screen readers for previous button when swiper is on first slide

itemRoleDescriptionMessagestring | nullnull

Message for screen readers describing the role of slide element

lastSlideMessagestring'This is the last slide'

Message for screen readers for previous button when swiper is on last slide

nextSlideMessagestring'Next slide'

Message for screen readers for next button

notificationClassstring'swiper-notification'

CSS class name of A11y notification

paginationBulletMessagestring'Go to slide {{index}}'

Message for screen readers for single pagination bullet

prevSlideMessagestring'Previous slide'

Message for screen readers for previous button

}

Custom Build

You have two options of making custom version of Swiper.

Using JS Modules

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

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

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

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

The following modules are exported:

  • 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
  • Thumbs - Thumbs module

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. Now, we need to install required dependencies. Go to the folder with downloaded and unzipped Swiper repository and execute in terminal:

    $ npm install
    
  4. 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',
        'thumbs',
      ],
      // default color of navigation elements
      themeColor: '#007aff',
      // additional color to be included
      colors: {
        white: '#ffffff',
        black: '#000000',
      },
    };
    
  5. Now, we are ready to build custom version of Swiper:

    $ npm run build:prod
    
  6. That is all. Generated CSS and JS files and their minified versions will be available in package/ folder.

TypeScript Definitions

Swiper (since version 6) is fully typed, it exports Swiper and SwiperOptions types:

// main.ts
import { Swiper, SwiperOptions } from 'swiper';

const swiperParams: SwiperOptions = {
  slidesPerView: 3,
  spaceBetween: 50,
};

const swiper = new Swiper('.swiper-container', swiperParams);

You can also check auto generated TypeScript definitions explorer for all the types, options, properties and methods.