Swiper API: Parameters

Let’s look on list of all available parameters:

ParameterTypeDefaultDescription
initbooleantrueWhether Swiper should be initialised automatically when you create an instance. If disabled, then you need to init it manually by calling mySwiper.init()
initialSlidenumber0Index number of initial slide.
directionstring‘horizontal’Could be ‘horizontal’ or ‘vertical’ (for vertical slider).
speednumber300Duration of transition between slides (in ms)
setWrapperSizebooleanfalseEnabled 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
virtualTranslatebooleanfalseEnabled 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
widthnumber 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
heightnumber 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
autoHeightbooleanfalseSet to true and slider wrapper will adopt its height to the height of the currently active slide
roundLengthsbooleanfalseSet to true to round values of slides width and height to prevent blurry texts on usual resolution screens (if you have such)
nestedbooleanfalseSet to true on nested Swiper for correct touch events interception. Use only on nested swipers that use same direction as the parent one
uniqueNavElementsbooleantrueIf 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
effectstring‘slide’Tranisition effect. Could be “slide”, “fade”, “cube”, “coverflow” or “flip”
runCallbacksOnInitbooleantrueFire [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
watchOverflowbooleanfalseWhen enabled Swiper will be disabled and hide navigation buttons on case there are not enough slides for sliding
onobject Register event handlers
Slides grid
spaceBetweennumber0Distance between slides in px.
slidesPerViewnumber or ‘auto’1Number 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
slidesPerColumnnumber1Number of slides per column, for multirow layoutslidesPerColumn > 1 is currently not compatible with loop mode (loop: true)
slidesPerColumnFillstring‘column’Could be ‘column’ or ‘row’. Defines how slides should fill rows, by column or by row
slidesPerGroupnumber1Set numbers of slides to define and enable group sliding. Useful to use with slidesPerView > 1
centeredSlidesbooleanfalseIf true, then active slide will be centered, not always on the left side.
slidesOffsetBeforenumber0Add (in px) additional slide offset in the beginning of the container (before all slides)
slidesOffsetAfternumber0Add (in px) additional slide offset in the end of the container (after all slides)
normalizeSlideIndexbooleantrueNormalize slide index. See #1766
Grab Cursor
grabCursorbooleanfalseThis option may a little improve desktop usability. If true, user will see the “grab” cursor when hover on Swiper
Touches
touchEventsTargetstring‘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)
touchRationumber1Touch ration
touchAnglenumber45Allowable angle (in degrees) to trigger touch move
simulateTouchbooleantrueIf true, Swiper will accept mouse events like touch events (click and drag to change slides)
shortSwipesbooleantrueSet to false if you want to disable short swipes
longSwipesbooleantrueSet to false if you want to disable long swipes
longSwipesRationumber0.5Ratio to trigger swipe to next/previous slide during long swipes
longSwipesMsnumber300Minimal duration (in ms) to trigger swipe to next/previous slide during long swipes
followFingerbooleantrueIf disabled, then slider will be animated only when you release it, it will not move while you hold your finger on it
allowTouchMovebooleantrueIf false, then the only way to switch the slide is use of external API functions like slidePrev or slideNext
thresholdnumber0Threshold value in px. If “touch distance” will be lower than this value then swiper will not move
touchMoveStopPropagationbooleantrueIf enabled, then propagation of “touchmove” will be stopped
iOSEdgeSwipeDetectionbooleanfalseEnable to release Swiper events for swipe-to-go-back work in iOS UIWebView
iOSEdgeSwipeThresholdnumber20Area (in px) from left edge of the screen to release touch events for swipe-to-go-back in iOS UIWebView
touchReleaseOnEdgesbooleanfalseEnable to release touch events on slider edge position (beginning, end) to allow for further page scrolling
passiveListenersbooleantruePassive 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
resistancebooleantrueSet to false if you want to disable resistant bounds
resistanceRationumber0.85This option allows you to control resistance ratio
Swiping / No swiping
preventInteractionOnTransitionbooleanfalseWhen enabled it won’t allow to change slides by swiping or navigation/pagination buttons during transition
allowSlidePrevbooleantrueSet to false to disable swiping to previous slide direction (to left or top)
allowSlideNextbooleantrueSet to false to disable swiping to next slide direction (to right or bottom)
noSwipingbooleantrueEnable/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
swipeHandlerstring / HTMLElementnullString with CSS selector or HTML element of the container with pagination that will work as only available handler for swiping
Clicks
preventClicksbooleantrueSet to true to prevent accidental unwanted clicks on links during swiping
preventClicksPropagationbooleantrueSet to true to stop clicks event propagation on links during swiping
slideToClickedSlidebooleanfalseSet to true and click on any slide will produce transition to this slide
Freemode
freeModebooleanfalseIf true then slides will not have fixed positions
freeModeMomentumbooleantrueIf true, then slide will keep moving for a while after you release it
freeModeMomentumRationumber1Higher value produces larger momentum distance after you release slider
freeModeMomentumVelocityRationumber1Higher value produces larger momentum velocity after you release slider
freeModeMomentumBouncebooleantrueSet to false if you want to disable momentum bounce in free mode
freeModeMomentumBounceRationumber1Higher value produces larger momentum bounce effect
freeModeMinimumVelocitynumber0.02Minimum touchmove-velocity required to trigger free mode momentum
freeModeStickybooleanfalseSet to true to enable snap to slides positions in free mode
Progress
watchSlidesProgressbooleanfalseEnable this feature to calculate each slides progress
watchSlidesVisibilitybooleanfalsewatchSlidesProgress should be enabled. Enable this option and slides that are in viewport will have additional visible class
Images
preloadImagesbooleantrueWhen enabled Swiper will force to load all images
updateOnImagesReadybooleantrueWhen enabled Swiper will be reinitialized after all inner images (<img> tags) are loaded. Required preloadImages: true
Loop
loopbooleanfalseSet to true to enable continuous loop modeIf you use it along with slidesPerView: 'auto' then you need to specify loopedSlides parameter with amount of slides to loop (duplicate)Also, because of nature of how the loop mode works, it will add duplicated slides. Such duplicated classes will have additional classes:swiper-slide-duplicate – represents duplicated slideswiper-slide-duplicate-active – represents slide duplicated to the currently active slideswiper-slide-duplicate-next – represents slide duplicated to the slide next to activeswiper-slide-duplicate-prev – represents slide duplicated to the slide previous to active
loopAdditionalSlidesnumber0Addition number of slides that will be cloned after creating of loop
loopedSlidesnumbernullIf you use slidesPerView:'auto' with loop mode you should tell to Swiper how many slides it should loop (duplicate) using this parameter
loopFillGroupWithBlankbooleanfalseEnable and loop mode will fill groups with insufficient number of slides with blank slides. Good to be used with slidesPerGroup parameter
Breakpoints
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 slidesPerViewslidesPerGroupspaceBetween. Such parameters like slidesPerColumnloopdirectioneffect won’t work. For example:var swiper = new Swiper('.swiper-container', { // Default parameters slidesPerView: 4, spaceBetween: 40, // Responsive breakpoints breakpoints: { // when window width is <= 320px 320: { slidesPerView: 1, spaceBetween: 10 }, // when window width is <= 480px 480: { slidesPerView: 2, spaceBetween: 20 }, // when window width is <= 640px 640: { slidesPerView: 3, spaceBetween: 30 } } })
Observer
observerbooleanfalseSet 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)
observeParentsbooleanfalseSet to true if you also need to watch Mutations for Swiper parent elements
Namespace
containerModifierClassstring‘swiper-container-‘The beginning of the modifier CSS class that can be added to swiper container depending on different parameters
slideClassstring‘swiper-slide’CSS class name of slide
slideActiveClassstring‘swiper-slide-active’CSS class name of currently active slide
slideDuplicateActiveClassstring‘swiper-slide-duplicate-active’CSS class name of duplicated slide which represents the currently active slide
slideVisibleClassstring‘swiper-slide-visible’CSS class name of currently visible slide
slideDuplicateClassstring‘swiper-slide-duplicate’CSS class name of slide duplicated by loop mode
slideNextClassstring‘swiper-slide-next’CSS class name of slide which is right after currently active slide
slideDuplicateNextClassstring‘swiper-slide-duplicate-next’CSS class name of duplicated slide which represents the slide next to active slide
slidePrevClassstring‘swiper-slide-prev’CSS class name of slide which is right before currently active slide
slideDuplicatePrevClassstring‘swiper-slide-duplicate-prev’CSS class name of duplicated slide which represents the slide previous to active slide
wrapperClassstring‘swiper-wrapper’CSS class name of slides’ wrapper

Leave a Comment

Your email address will not be published.