<!-- 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>
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:
var mySwiper = new Swiper('.swiper-container', {
speed: 400,
spaceBetween: 100
});
Let's look on list of all available parameters:
Parameter | Type | Default | Description |
---|---|---|---|
initialSlide | number | 0 | Index number of initial slide. |
direction | string | 'horizontal' | Could be 'horizontal' or 'vertical' (for vertical slider). |
speed | number | 300 | Duration of transition between slides (in ms) |
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 |
Autoplay | |||
autoplay | number | - |
Delay between transitions (in ms). If this parameter is not specified, auto play will be disabled If you need to specify different delay for specifi slides you can do it by using
|
autoplayStopOnLast | boolean | false | Enable this parameter and autoplay will be stopped when it reaches last slide (has no effect in loop mode) |
autoplayDisableOnInteraction | boolean | true | Set to false and autoplay will not be disabled after user interactions (swipes), it will be restarted every time after interaction |
Progress | |||
watchSlidesProgress | boolean | false | Enable this feature to calculate each slides progress |
watchSlidesVisibility | boolean | false | watchSlidesProgress should be enabled. Enable this option and slides that are in viewport will have additional visible class |
Freemode | |||
freeMode | boolean | false | If true then slides will not have fixed positions |
freeModeMomentum | boolean | true | If true, then slide will keep moving for a while after you release it |
freeModeMomentumRatio | number | 1 | Higher value produces larger momentum distance after you release slider |
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 |
Effects | |||
effect | string | 'slide' | Could be "slide", "fade", "cube", "coverflow" or "flip" |
fade | object |
|
Fade effect parameters |
cube | object |
|
Cube effect parameters. For better performance you may disable shadows |
coverflow | object |
|
Coverflow effect parameters. For better performance you may disable shadows |
flip | object |
|
Flip effect parameters. limitRotation (when enabled) limits slides rotation angle to 180deg maximum. It allows to quickly "flip" between different slides. If you use "slow" transitions then it is better to disable it. |
Parallax | |||
parallax | boolean | false | Enable, if you want to use "parallaxed" elements inside of slider |
Slides grid | |||
spaceBetween | number | 0 | Distance between slides in px. |
slidesPerView | number or 'auto' | 1 |
Number of slides per view (slides visible at the same time on slider's container). 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 |
slidesPerColumnFill | string | 'column' | Could be 'column' or 'row'. Defines how slides should fill rows, by column or by row |
slidesPerGroup | number | 1 | Set numbers of slides to define and enable group sliding. Useful to use with slidesPerView > 1 |
centeredSlides | boolean | false | If true, then active slide will be centered, not always on the left side. |
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) |
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 | 'container' | 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 ration |
touchAngle | number | 45 | Allowable angle (in degrees) to trigger touch move |
simulateTouch | boolean | true | If true, Swiper will accept mouse events like touch events (click and drag to change slides) |
shortSwipes | boolean | true | Set to false if you want to disable short swipes |
longSwipes | boolean | true | Set to false if you want to disable long swipes |
longSwipesRatio | number | 0.5 | Ratio to trigger swipe to next/previous slide during long swipes |
longSwipesMs | number | 300 | Minimal duration (in ms) to trigger swipe to next/previous slide during long swipes |
followFinger | boolean | true | If disabled, then slider will be animated only when you release it, it will not move while you hold your finger on it |
onlyExternal | boolean | false | If true, then the only way to switch the slide is use of external API functions like slidePrev or slideNext |
threshold | number | 0 | Threshold value in px. If "touch distance" will be lower than this value then swiper will not move |
touchMoveStopPropagation | boolean | true | If enabled, then propagation of "touchmove" will be stopped |
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 |
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 |
Swiping / No swiping | |||
allowSwipeToPrev | boolean | true | Set to false to disable swiping to previous slide direction (to left or top) |
allowSwipeToNext | boolean | true | Set to false to disable swiping to next slide direction (to right or bottom) |
noSwiping | boolean | true | Will disable swiping on elements matched to class specified in noSwipingClass |
noSwipingClass | string | 'swiper-no-swiping' | If true, then you can add noSwipingClass class to swiper's slide to prevent/disable swiping on this element |
swipeHandler | string / HTMLElement | null | String with CSS selector or HTML element of the container with pagination that will work as only available handler for swiping |
Navigation Controls | |||
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 |
Pagination | |||
pagination | string / HTMLElement | null | String with CSS selector or HTML element of the container with pagination |
paginationType | string | 'bullets' | String with type of pagination. Can be "bullets", "fraction", "progress" or "custom" |
paginationHide | boolean | true | Toggle (hide/true) pagination container visibility when click on Slider's container |
paginationClickable | boolean | false | If true then clicking on pagination button will cause transition to appropriate slide. Only for bullets pagination type |
paginationElement | string | 'span' | Defines which HTML tag will be use to represent single pagination bullet. . Only for bullets pagination type |
paginationBulletRender(swiper, index, className) | function | 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
For example, with this code, we can add slide number into pagination bullet:
|
paginationFractionRender(swiper, currentClassName, totalClassName) | function | null | This parameter allows to customize "fraction" pagination html. Only for fraction pagination type
For example:
|
paginationProgressRender(swiper, progressbarClass) | function | null | This parameter allows to customize "progress" pagination. Only for progress pagination type
For example:
|
paginationCustomRender(swiper, current, total) | function | null | This parameter is required for custom pagination type where you have to specify how it should be rendered
For example:
|
Navigation Buttons | |||
nextButton | string / HTMLElement | null | String with CSS selector or HTML element of the element that will work like "next" button after click on it |
prevButton | string / HTMLElement | null | String with CSS selector or HTML element of the element that will work like "prev" button after click on it |
Scollbar | |||
scrollbar | string / HTMLElement | null | String with CSS selector or HTML element of the container with scrollbar. |
scrollbarHide | boolean | true | Hide scrollbar automatically after user interaction |
scrollbarDraggable | boolean | false | Set to true to enable make scrollbar draggable that allows you to control slider position |
scrollbarSnapOnRelease | boolean | false | Set to true to snap slider position to slides when you release scrollbar |
Accessibility | |||
a11y | boolean | false | Option to enable keyboard accessibility to provide foucsable navigation buttons and basic ARIA for screen readers |
prevSlideMessage | string | 'Previous slide' | Message for screen readers for previous button |
nextSlideMessage | string | 'Next slide' | Message for screen readers for next button |
firstSlideMessage | string | 'This is the first slide' | Message for screen readers for previous button when swiper is on first slide |
lastSlideMessage | string | 'This is the last slide' | Message for screen readers for previous button when swiper is on last slide |
paginationBulletMessage | string | 'Go to slide {{index}}' | Message for screen readers for single pagination bullet |
Keyboard / Mousewheel | |||
keyboardControl | boolean | false | Set to true to enable navigation through slides using keyboard right and left (for horizontal mode), top and borrom (for vertical mode) keyboard arrows |
mousewheelControl | boolean | false | Set to true to enable navigation through slides using mouse wheel |
mousewheelForceToAxis | boolean | false | Set to true to force mousewheel swipes to axis. So in horizontal mode mousewheel will work only with horizontal mousewheel scrolling, and only with vertical scrolling in vertical mode. |
mousewheelReleaseOnEdges | boolean | false | 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) |
mousewheelInvert | boolean | false | Set to true to invert sliding direction |
mousewheelSensitivity | number | 1 | Multiplier of mousewheel data, allows to tweak mouse wheel sensitivity |
mousewheelEventsTarged | string / HTMLElement | 'container' | String with CSS selector or HTML element of the container accepting mousewheel events. By default it is swiper-container |
Hash/History Navigation | |||
hashnav | boolean | false | Set to true to enable hash url navigation to for slides |
hashnavWatchState | boolean | false | Set to true to enable also navigation through slides (when hashnav is enabled) by browser history or by setting directly hash on document location |
history | string | 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.
|
|
replaceState | boolean | false | Works in addition to hashnav or history to replace current url state with the new one instead of adding it to history |
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 |
lazyLoading | boolean | false | Set to "true" to enable images lazy loading. Note that preloadImages should be disabled |
lazyLoadingInPrevNext | boolean | false | Set to "true" to enable lazy loading for the closest slides images (for previous and next slide images) |
lazyLoadingInPrevNextAmount | number | 1 | Amount of next/prev slides to preload lazy images in. Can't be less than slidesPerView |
lazyLoadingOnTransitionStart | boolean | false | 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 |
Loop | |||
loop | boolean | false |
Set to true to enable continuous loop mode If you use it along with Also, because of nature of how the loop mode works, it will add duplicated slides. Such duplicated classes will have additional classes:
|
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 |
Zoom | |||
zoom | boolean | false | Set to true to enable zooming functionality |
zoomMax | number | 3 | Maximum image zoom multiplier |
zoomMin | number | 1 | Minimal image zoom multiplier |
zoomToggle | boolean | true | Enable/disable zoom-in by slide's double tap |
Controller | |||
control | [Swiper Instance] | undefined | Pass here another Swiper instance or array with Swiper instances that should be controlled by this Swiper |
controlInverse | boolean | false | Set to true and controlling will be in inverse direction |
controlBy | string | 'slide' | Can be 'slide' or 'container' . 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) |
normalizeSlideIndex | boolean | true | Normalize slide index in control mode. See #1766 |
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 |
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 . Such parameters like slidesPerColumn , loop , direction , effect won't work. For example:
|
|
Callbacks | |||
runCallbacksOnInit | boolean | true | Run on[Transition/SlideChange][Start/End] callbacks on swiper initialization. Such callbacks will be fired on initialization in case of your initialSlide is not 0, or you use loop mode |
onInit(swiper) | function | Callback function, will be executed right after Swiper initialization | |
onSlideChangeStart(swiper) | function | Callback function, will be executed in the beginning of animation to other slide (next or previous). Receives swiper instance as an argument. | |
onSlideChangeEnd(swiper) | function | Callback function, will be executed after animation to other slide (next or previous). Receives slider instance as an argument. | |
onSlideNextStart(swiper) | function | Same as "onSlideChangeStart" but for "forward" direction only | |
onSlideNextEnd(swiper) | function | Same as "onSlideChangeEnd" but for "forward" direction only | |
onSlidePrevStart(swiper) | function | Same as "onSlideChangeStart" but for "backward" direction only | |
onSlidePrevEnd(swiper) | function | Same as "onSlideChangeEnd" but for "backward" direction only | |
onTransitionStart(swiper) | function | Callback function, will be executed in the beginning of transition. Receives swiper instance as an argument. | |
onTransitionEnd(swiper) | function | Callback function, will be executed after transition. Receives slider instance as an argument. | |
onTouchStart(swiper, event) | function | Callback function, will be executed when user touch Swiper. Receives swiper instance and 'touchstart' event as an arguments. | |
onTouchMove(swiper, event) | function | Callback function, will be executed when user touch and move finger over Swiper. Receives swiper instance and 'touchmove' event as an arguments. | |
onTouchMoveOpposite(swiper, event) | function | Callback function, will be executed when user touch and move finger over Swiper in direction opposite to direction parameter. Receives swiper instance and 'touchmove' event as an arguments. |
|
onSliderMove(swiper, event) | function | Callback function, will be executed when user touch and move finger over Swiper and move it. Receives swiper instance and 'touchmove' event as an arguments. | |
onTouchEnd(swiper, event) | function | Callback function, will be executed when user release Swiper. Receives swiper instance and 'touchend' event as an arguments. | |
onClick(swiper, event) | function | Callback function, will be executed when user click/tap on Swiper after 300ms delay. Receives swiper instance and 'touchend' event as an arguments. | |
onTap(swiper, event) | function | Callback function, will be executed when user click/tap on Swiper. Receives swiper instance and 'touchend' event as an arguments. | |
onDoubleTap(swiper, event) | function | Callback function, will be executed when user double tap on Swiper's container. Receives swiper instance and 'touchend' event as an arguments | |
onImagesReady(swiper) | function | Callback function, will be executed right after all inner images are loaded. updateOnImagesReady should be also enabled |
|
onProgress(swiper, progress) | function | Callback function, will be executed when Swiper progress is changed, as second arguments it receives progress that is always from 0 to 1 | |
onReachBeginning(swiper) | function | Callback function, will be executed when Swiper reach its beginning (initial position) | |
onReachEnd(swiper) | function | Callback function, will be executed when Swiper reach last slide | |
onDestroy(swiper) | function | Callback function, will be executed when you destroy Swiper | |
onSetTranslate(swiper, translate) | function | Callback function, will be executed when swiper's wrapper change its position. Receives swiper instance and current translate value as an arguments | |
onSetTransition(swiper, transition) | function | Callback function, will be executed everytime when swiper starts animation. Receives swiper instance and current transition duration (in ms) as an arguments | |
onAutoplay(swiper) | function | Same as onSlideChangeStart but caused by autoplay |
|
onAutoplayStart(swiper) | function | Callback function, will be executed when when autoplay started | |
onAutoplayStop(swiper) | function | Callback function, will be executed when when autoplay stopped | |
onLazyImageLoad(swiper, slide, image) | function | Callback function, will be executed in the beginning of lazy loading of image | |
onLazyImageReady(swiper, slide, image) | function | Callback function, will be executed when lazy loading image will be loaded | |
onPaginationRendered(swiper, paginationContainer) | function | Callback function, will be executed after pagination elements generated and added to DOM | |
onScroll(swiper, e) | function | Callback function, will be executed when slider sliding or scrolling happens with mousehweel control | |
onBeforeResize(swiper) | function | Callback function, will be executed on window resize right before swiper's onresize manipulation | |
onAfterResize(swiper) | function | Callback function, will be executed on window resize right after swiper's onresize manipulation | |
onKeyPress(swiper, kc) | function | Callback function, will be executed on "keydown" event when keyboard control is enabled | |
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 |
slideDuplicatedActiveClass | 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 |
slideDuplicatedNextClass | 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 |
slideDuplicatedPrevClass | 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 |
bulletClass | string | 'swiper-pagination-bullet' | CSS class name of single pagination bullet |
bulletActiveClass | string | 'swiper-pagination-bullet-active' | CSS class name of currently active pagination bullet |
paginationHiddenClass | string | 'swiper-pagination-hidden' | CSS class name of pagination when it becomes inactive |
paginationCurrentClass | string | 'swiper-pagination-current' | CSS class name of the element with currently active index in "fraction" pagination |
paginationTotalClass | string | 'swiper-pagination-total' | CSS class name of the element with total number of "snaps" in "fraction" pagination |
paginationProgressbarClass | string | 'swiper-pagination-progressbar' | CSS class name of pagination progressbar |
paginationClickableClass | string | 'swiper-pagination-clickable' | CSS class name set to pagination when it is clickable |
paginationModifierClass | string | 'swiper-pagination-' | The beginning of the modifier CSS class name that will be added to pagination depending on parameters |
buttonDisabledClass | string | 'swiper-button-disabled' | CSS class name of next/prev button when it becomes disabled |
lazyLoadingClass | string | 'swiper-lazy' | CSS class name of lazy element |
lazyStatusLoadingClass | string | 'swiper-lazy-loading' | CSS class name of lazy loading element |
lazyStatusLoadedClass | string | 'swiper-lazy-loaded' | CSS class name of lazy loaded element |
lazyPreloaderClass | string | 'swiper-lazy-preloader' | CSS class name of lazy preloader |
preloaderClass | string | 'preloader' | CSS class name of additional lazy preloader |
zoomContainerClass | string | 'swiper-zoom-container' | CSS class name of zoom container |
notificationClass | string | 'swiper-notification' | CSS class name of a11 notification |
After we initialize Slider we have its initialized instance in variable (like mySwiper
variable in example above) with helpful methods and properties:
Properties | |
---|---|
mySwiper.params | Object with passed initialization parameters |
mySwiper.container | Dom7/jQuery element with slider container HTML element. To get vanilla HTMLElement use mySwiper.container[0] |
mySwiper.wrapper | Dom7/jQuery element with slider wrapper HTML element. To get vanilla HTMLElement use mySwiper.wrapper[0] |
mySwiper.slides | Dom7/jQuery array-like collection of slides HTML elements. To get specific slide HTMLElement use mySwiper.slides[1] |
mySwiper.nextButton | Dom7/jQuery element with next button HTML element. To get vanilla HTMLElement use mySwiper.nextButton[0] |
mySwiper.prevButton | Dom7/jQuery element with prev button HTML element. To get vanilla HTMLElement use mySwiper.prevButton[0] |
mySwiper.bullets | Dom7/jQuery collection of pagination buttons HTML elements. To get specific slide HTMLElement use mySwiper.bullets[1] |
mySwiper.width | Width of container |
mySwiper.height | Height of container |
mySwiper.translate | Current value of wrapper translate |
mySwiper.progress | Current progress of wrapper translate (from 0 to 1) |
mySwiper.activeIndex |
Index number of currently active slide Note, that in loop mode active index value will be always shifted on a number of looped/duplicated slides |
mySwiper.realIndex |
Index number of currently active slide considering duplicated slides in loop mode |
mySwiper.previousIndex | Index number of previously active slide |
mySwiper.isBeginning | true if slider on most "left"/"top" position |
mySwiper.isEnd | true if slider on most "right"/"bottom" position |
mySwiper.autoplaying | true if autoplay is enabled |
mySwiper.animating | true if swiper is in transition |
mySwiper.touches | Object with the following touch event properties:
|
mySwiper.clickedIndex | Index number of last clicked slide |
mySwiper.clickedSlide | Link to last clicked slide (HTMLElement) |
Methods | |
mySwiper.slideNext(runCallbacks, speed); |
Run transition to next slide
|
mySwiper.slidePrev(runCallbacks, speed); |
Run transition to previous slide
|
mySwiper.slideTo(index, speed, runCallbacks); |
Run transition to the slide with index number equal to 'index' parameter for the duration equal to 'speed' parameter.
|
mySwiper.update(updateTranslate); |
This method includes updateContainerSize, updateSlidesSize, updateProgress, updatePagination and updateClasses methods You should call it after you add/remove slides manually, or after you hide/show it, or do any custom DOM modifications with Swiper
This method also includes subcall of the following methods which you can use separately:
|
mySwiper.onResize(); | Swiper executes this method when you resize browser. It is almost the same as .update() but a bit softer, without hard setting translate |
mySwiper.detachEvents(); | Detach all events listeners |
mySwiper.attachEvents(); | Atach all events listeners again |
mySwiper.startAutoplay(); | start auto play. It may be useful for custom "Play" and "Pause" buttons |
mySwiper.stopAutoplay(); | stop auto play. It may be useful for custom "Play" and "Pause" buttons |
mySwiper.destroy(deleteInstance, cleanupStyles); |
mySwiper.appendSlide([ '<div class="swiper-slide">Slide 10"</div>', '<div class="swiper-slide">Slide 11"</div>' ]); |
mySwiper.prependSlide(slides); | Add new slides to the beginning. slides could be HTMLElement or HTML string with new slide or array with such slides, for example:
|
mySwiper.removeSlide(slideIndex); | Remove selected slides. slideIndex could be a number with slide index to remove or array with indexes, for example:
|
mySwiper.removeAllSlides(); | Remove all slides |
mySwiper.setWrapperTranslate(translate); | Set custom css3 transform's translate value for swiper wrapper |
mySwiper.getWrapperTranslate(); | Get current value of swiper wrapper css3 transform translate |
mySwiper.on(callback, handler) | Add callback/event handler |
mySwiper.once(callback, handler) | Add event/callback that will be executed only once |
mySwiper.off(callback) | Remove all handlers for specified callback/event |
mySwiper.lockSwipeToNext() mySwiper.unlockSwipeToNext() |
Disable (lock) / enable (unlock) ability to slide to the next slides |
mySwiper.lockSwipeToPrev() mySwiper.unlockSwipeToPrev() |
Disable (lock) / enable (unlock) ability to slide to the previous slides |
mySwiper.lockSwipes() mySwiper.unlockSwipes() |
Disable (lock) / enable (unlock) ability to change slides |
mySwiper.disableMousewheelControl(); | Disable mousewheel control |
mySwiper.enableMousewheelControl(); | Enable mousewheel control |
mySwiper.disableKeyboardControl(); | Disable keyboard control |
mySwiper.enableKeyboardControl(); | Enable keyboard control |
mySwiper.disableTouchControl(); | Disable touch control |
mySwiper.enableTouchControl(); | Enable touch control |
mySwiper.unsetGrabCursor(); | Unset grab cursor |
mySwiper.setGrabCursor(); | Set grab cursor |
Hash navigation is intended to have a link to specific slide that allows to load page with specific slide opened.
To make it work, you need to enable it by passing hashnav:true
parameter and adding slides hashes in data-hash
attribute:
<div class="swiper-container">
<div class="swiper-wrapper">
<div class="swiper-slide" data-hash="slide1">Slide 1</div>
<div class="swiper-slide" data-hash="slide2">Slide 2</div>
<div class="swiper-slide" data-hash="slide3">Slide 3</div>
<div class="swiper-slide" data-hash="slide4">Slide 4</div>
<div class="swiper-slide" data-hash="slide5">Slide 5</div>
...
</div>
</div>
var swiper = new Swiper('.swiper-container', {
//enable hash navigation
hashnav: true
})
Since version 3.0.3 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 data-swiper-parallax
attribute on required elements
<div class="swiper-container">
<!-- Parallax background element -->
<div
class="parallax-bg"
style="background-image:url(http://lorempixel.com/900/600/nightlife/2/)"
data-swiper-parallax="-23%">
</div>
<div class="swiper-wrapper">
<div class="swiper-slide">
<!-- Each slide has parallax title -->
<div class="title" data-swiper-parallax="-100">Slide 1</div>
<!-- Parallax subtitle -->
<div class="subtitle" data-swiper-parallax="-200">Subtitle</div>
<!-- And parallax text with custom transition duration -->
<div class="text" data-swiper-parallax="-300" data-swiper-parallax-duration="600">
<p>Lorem ipsum dolor sit amet, ...</p>
</div>
</div>
...
</div>
</div>
All elements with specified data-swiper-parallax
attribute will have parallax transition. This attribute may accept:
- 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
It is possible to overwrite parallax direction by using data-swiper-parallax-x
and data-swiper-parallax-y
attributes with same rules
You can also pass custom transition duration for parallax elements by adding data-swiper-parallax-duration
attribute.
To enable lazy loading, first of all we need special layout for images or elements with backround in slides:
<div class="swiper-container"> <div class="swiper-wrapper"><!-- Lazy image --> <div class="swiper-slide"> <img data-src="path/to/picture-1.jpg" class="swiper-lazy"> <div class="swiper-lazy-preloader"></div> </div>
<!-- Lazy image with srscet--> <div class="swiper-slide"> <img data-src="path/to/logo-small.png" data-srcset="path/logo/logo-large.png 2x" class="swiper-lazy"> <div class="swiper-lazy-preloader"></div> </div>
<!-- Element with lazy background image --> <div class="swiper-slide"> <div data-background="path/to/picture-2.jpg" class="swiper-lazy"> <div class="swiper-lazy-preloader"></div> </div> </div>
<!-- Lazy background image on slide itself --> <div data-background="path/to/picture-3.jpg" class="swiper-slide swiper-lazy"> <div class="swiper-lazy-preloader"></div> </div> </div> </div>
As you see:
- Each lazy loaded image/element should have additional "swiper-lazy" class
- Lazy image source for <img> element should be specified in "data-src" attribute instead of "src"
- Lazy image source set for <img> element should be specified in "data-srcset" attribute instead of "srcset"
- Lazy background image source should be specified in "data-background" attribute
You may also add animated preloader spinner to slide which will be removed automatically after image loaded:
<div class="swiper-lazy-preloader"></div>
Or white-one for dark layout:
<div class="swiper-lazy-preloader swiper-lazy-preloader-white"></div>
After that we need to enable lazy loading on Swiper initialization:
var swiper = new Swiper('.swiper-container', {
// Disable preloading of all images
preloadImages: false,
// Enable lazy loading
lazyLoading: true
});
If you use slidesPerView "auto" or slidesPerView > 1, then you should also enable watchSlidesVisibility and Swiper will load images in currently visible slides
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-side">
<div class="swiper-zoom-container">
<img src="path/to/image1.jpg">
</div>
</div>
<div class="swiper-side">
<div class="swiper-zoom-container">
<img src="path/to/image2.jpg">
</div>
</div>
<div class="swiper-side">Plain slide with text</div>
<div class="swiper-side">
<!-- Override maxZoom 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. Note, it doesn't support to zoom anything else except single image.
You can override maxZoom
parameter for specific slides by using data-swiper-zoom
attribute on zoom container.
Emitter API allows to you add events/callbacks to Swiper like usual events, even after Swiper initialization:
// Init Swiper var mySwiper = new Swiper('.swiper-container');
// Later add callback mySwiper.on('slideChangeStart', function () { console.log('slide change start'); });
// Add one more handler for this event mySwiper.on('slideChangeStart', function () { console.log('slide change start 2'); });
// Add handler that will be executed only once mySwiper.once('sliderMove', function () { console.log('slider moved'); });
// Somewhen later, remove all slideChangeStart handlers mySwiper.off('slideChangeStart');
Note, that callback/event name in this case is the same as usual callback name but without "on" and with lowercase first character, so "onTouchMove" becames just "touchMove"
If you initialize Swiper using HTML it is still possible to access to Swiper's instance. It is swiper
property of Swiper's HTML container element:
var mySwiper = $('.swiper-container')[0].swiper;
// Now you can use all slider methods like mySwiper.slideNext();
Since version 3.4.0 Swiper comes with Gulp builder that allows to build custom library version where you may include only required modules. We need the following:
- Download and unzip Swiper GitHub repository to local folder
- Install Node.js (if not installed)
- Install Gulp (if not installed) by executing the following command in terminal:
$ npm install --global gulp
- Now, we need to install required dependencies. Go to the folder with downloaded and unzipped Swiper repository and execute in terminal:
$ npm install
- Now, we are ready to build custom version of Framework7. We need to execute gulp custom command and pass components/modules that we want to include as argument. For example, if we want to include just Accordion and Tabs:
$ gulp custom -zoom,lazy-loading,effects
Note, that there shouldn't be spaces between comma and components name - That is all. Now you should see new custom/ folder that will contain custom JS and CSS files and their minified versions
Following modules are available:
effects
lazy-load
scrollbar
controller
hashnav
history
keyboard
mousewheel
parallax
zoom
a11y