Slider
Swiper is the most modern free mobile touch slider with hardware accelerated transitions and amazing native behavior. It is intended to be used in mobile websites
Introduce
Add slider_js,slider_css to vendors computed
Beae Swiper API
Initialize Swiper
Now, when we have Swiper's HTML, we need to initialize it using the following function:
new BeaeSwiper(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
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:
Parameters
Let's look on list of all available parameters:
Name
Type
Default
Description
allowSlideNext
boolean
true
Set to false to disable swiping to next slide direction (to right or bottom)
allowSlidePrev
boolean
true
Set to false to disable swiping to previous slide direction (to left or top)
allowTouchMove
boolean
true
If false, then the only way to switch the slide is use of external API functions like slidePrev or slideNext
autoHeight
boolean
false
Set to true and slider wrapper will adapt its height to the height of the currently active slide
breakpoints
object
Allows to set different parameter for different responsive breakpoints (screen sizes). Not all parameters can be changed in breakpoints, only those which are not required different layout and logic, like slidesPerView, slidesPerGroup, spaceBetween, slidesPerColumn. Such parameters like loop and effect won't work
breakpointsBase
string
'window'
Base for breakpoints (beta). Can be window or container. If set to window (by default) then breakpoint keys mean window width. If set to container then breakpoint keys treated as swiper container width
centerInsufficientSlides
boolean
false
When enabled it center slides if the amount of slides less than slidesPerView. Not intended to be used loop mode and slidesPerColumn
centeredSlides
boolean
false
If true, then active slide will be centered, not always on the left side.
centeredSlidesBounds
boolean
false
If true, then active slide will be centered without adding gaps at the beginning and end of slider. Required centeredSlides: true. Not intended to be used with loop or pagination
containerModifierClass
string
'swiper-container-'
The beginning of the modifier CSS class that can be added to swiper container depending on different parameters
createElements
boolean
false
When enabled Swiper will automatically wrap slides with swiper-wrapper element, and will create required elements for navigation, pagination and scrollbar they are enabled (with their respective params object or with boolean true))
cssMode
boolean
false
When enabled it will use modern CSS Scroll Snap API. It doesn't support all of Swiper's features, but potentially should bring a much better performance in simple configurations.
This is what is not supported when it is enabled:
All effects (Fade, Coverflow, Flip, Cube)
Zoom
Virtual Slides
speedparameter will have no effectAll transition start/end related events (use
slideChangeinstead)slidesPerGrouphas limited supportcenteredSlidesis not supportedChanging 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)simulateTouchdoesn't have effect and "dragging" with mouse doesn't workresistancedoesn't have any effectallowSlidePrev/NextswipeHandlerfreeModeand all relevant features
direction
'horizontal' | 'vertical'
'horizontal'
Can be 'horizontal' or 'vertical' (for vertical slider).
edgeSwipeDetection
string | boolean
false
Enable to release Swiper events for swipe-back work in app. If set to 'prevent' then it will prevent system swipe-back navigation instead
edgeSwipeThreshold
number
20
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'
enabled
boolean
true
Whether Swiper initially enabled. When Swiper is disabled, it will hide all navigation elements and won't respond to any events and interactions
focusableElements
string
'input, select, option, textarea, button, video, label'
CSS selector for focusable elements. Swiping will be disabled on such elements if they are "focused"
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
freeMode
boolean
false
If enabled then slides will not have fixed positions
freeModeMinimumVelocity
number
0.02
Minimum touchmove-velocity required to trigger free mode momentum
freeModeMomentum
boolean
true
If enabled, then slide will keep moving for a while after you release it
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
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
freeModeSticky
boolean
false
Set to enabled to enable snap to slides positions in free mode
grabCursor
boolean
false
This option may a little improve desktop usability. If true, user will see the "grab" cursor when hover on Swiper
height
number
null
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
init
boolean
true
Whether Swiper should be initialised automatically when you create an instance. If disabled, then you need to init it manually by calling swiper.init()
initialSlide
number
0
Index number of initial slide.
longSwipes
boolean
true
Set to false if you want to disable long swipes
longSwipesMs
number
300
Minimal duration (in ms) to trigger swipe to next/previous slide during long swipes
longSwipesRatio
number
0.5
Ratio to trigger swipe to next/previous slide during long swipes
loop
boolean
false
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 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
loopAdditionalSlides
number
0
Addition number of slides that will be cloned after creating of loop
loopFillGroupWithBlank
boolean
false
Enable and loop mode will fill groups with insufficient number of slides with blank slides. Good to be used with slidesPerGroup parameter
loopPreventsSlide
boolean
true
When enabled it prevents Swiper slide prev/next transitions when transitions is already in progress (has effect when loop enabled)
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
nested
boolean
false
Set to true on Swiper for correct touch events interception. Use only on swipers that use same direction as the parent one
noSwiping
boolean
true
Enable/disable swiping on elements matched to class specified in noSwipingClass
noSwipingClass
string
'swiper-no-swiping'
Specify noSwiping's element css class
noSwipingSelector
string
Can be used instead of noSwipingClass to specify elements to disable swiping on. For example 'input' will disable swiping on all inputs
normalizeSlideIndex
boolean
true
Normalize slide index.
observeParents
boolean
false
Set to true if you also need to watch Mutations for Swiper parent elements
observeSlideChildren
boolean
false
Set to true if you also need to watch Mutations for Swiper slide children elements
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)
on
object
Register event handlers
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
preloadImages
boolean
true
When enabled Swiper will force to load all images
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
preventInteractionOnTransition
boolean
false
When enabled it won't allow to change slides by swiping or navigation/pagination buttons during transition
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
resizeObserver
boolean
false
When enabled it will use ResizeObserver (if supported by browser) on swiper container to detect container resize (instead of watching for window resize)
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)
runCallbacksOnInit
boolean
true
Fire Transition/SlideChange/Start/End events on swiper initialization. Such events will be fired on initialization in case of your initialSlide is not 0, or you use loop mode
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
shortSwipes
boolean
true
Set to false if you want to disable short swipes
simulateTouch
boolean
true
If true, Swiper will accept mouse events like touch events (click and drag to change slides)
slideActiveClass
string
'swiper-slide-active'
CSS class name of currently active slide
slideBlankClass
string
'swiper-slide-invisible-blank'
CSS class name of blank slide append to fill groups in loop mode when loopFillGroupWithBlank is also enabled
slideClass
string
'swiper-slide'
CSS class name of slide
slideDuplicateActiveClass
string
'swiper-slide-duplicate-active'
CSS class name of duplicated slide which represents the currently active slide
slideDuplicateClass
string
'swiper-slide-duplicate'
CSS class name of slide duplicated by loop mode
slideDuplicateNextClass
string
'swiper-slide-duplicate-next'
CSS class name of duplicated slide which represents the slide next to active slide
slideDuplicatePrevClass
string
'swiper-slide-duplicate-prev'
CSS class name of duplicated slide which represents the slide previous to active slide
slideNextClass
string
'swiper-slide-next'
CSS class name of slide which is right after currently active slide
slidePrevClass
string
'swiper-slide-prev'
CSS class name of slide which is right before currently active slide
slideToClickedSlide
boolean
false
Set to true and click on any slide will produce transition to this slide
slideVisibleClass
string
'swiper-slide-visible'
CSS class name of currently visible slide
slidesOffsetAfter
number
0
Add (in px) additional slide offset in the end of the container (after all slides)
slidesOffsetBefore
number
0
Add (in px) additional slide offset in the beginning of the container (before all slides)
slidesPerColumn
number
1
Number of slides per column, for multirow layout
slidesPerColumnFill
'row' | 'column'
'column'
Can 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
slidesPerGroupSkip
number
0
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.
slidesPerView
number | 'auto'
1
Number of slides per view (slides visible at the same time on slider's container).
spaceBetween
number
0
Distance between slides in px.
speed
number
300
Duration of transition between slides (in ms)
swipeHandler
HTMLElement | CSSSelector
null
String with CSS selector or HTML element of the container with pagination that will work as only available handler for swiping
threshold
number
0
Threshold value in px. If "touch distance" will be lower than this value then swiper will not move
touchAngle
number
45
Allowable angle (in degrees) to trigger touch move
touchEventsTarget
'container' | 'wrapper'
'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)
touchMoveStopPropagation
boolean
false
If enabled, then propagation of "touchmove" will be stopped
touchRatio
number
1
Touch ratio
touchReleaseOnEdges
boolean
false
Enable to release touch events on slider edge position (beginning, end) to allow for further page scrolling
touchStartForcePreventDefault
boolean
false
Force to always prevent default for touchstart (mousedown) event
touchStartPreventDefault
boolean
true
If disabled, touchstart (mousedown) event won't be prevented
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
updateOnImagesReady
boolean
true
When enabled Swiper will be reinitialized after all inner images ( tags) are loaded. Required preloadImages: true
updateOnWindowResize
boolean
true
Swiper will recalculate slides position on window resize (orientationchange)
url
string
null
Required for active slide detection when rendered on server-side and enabled history
userAgent
string
null
userAgent string. Required for browser/device detection when rendered on server-side
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
watchOverflow
boolean
false
When enabled Swiper will be disabled and hide navigation buttons on case there are not enough slides for sliding.
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
width
number
null
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
wrapperClass
string
'swiper-wrapper'
CSS class name of slides' wrapper
onAny
function
Add event listener that will be fired on all events
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.$el
Dom7Array
Dom7 element with slider container HTML element. To get vanilla HTMLElement use swiper.el
swiper.$wrapperEl
Dom7Array
Dom7 element with slider wrapper HTML element. To get vanilla HTMLElement use swiper.wrapperEl
swiper.activeIndex
number
Index number of currently active slide
swiper.allowSlideNext
boolean
Disable / enable ability to slide to the next slides by assigning false / true to this property
swiper.allowSlidePrev
boolean
Disable / enable ability to slide to the previous slides by assigning false / true to this property
swiper.allowTouchMove
boolean
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.animating
boolean
true if swiper is in transition
swiper.clickedIndex
number
Index number of last clicked slide
swiper.clickedSlide
HTMLElement
Link to last clicked slide (HTMLElement)
swiper.el
HTMLElement
Slider container HTML element
swiper.height
number
Height of container
swiper.isBeginning
boolean
true if slider on most "left"/"top" position
swiper.isEnd
boolean
true if slider on most "right"/"bottom" position
swiper.params
SwiperOptions
Object with passed initialization parameters
swiper.previousIndex
number
Index number of previously active slide
swiper.progress
number
Current progress of wrapper translate (from 0 to 1)
swiper.realIndex
number
Index number of currently active slide considering duplicated slides in loop mode
swiper.slides
Dom7Array
Dom7 array-like collection of slides HTML elements. To get specific slide HTMLElement use swiper.slides[1]
swiper.touches
object
Object with the following touch event properties:
swiper.touches.startXswiper.touches.startYswiper.touches.currentXswiper.touches.currentYswiper.touches.diff
swiper.translate
number
Current value of wrapper translate
swiper.width
number
Width of container
swiper.wrapperEl
HTMLElement
Wrapper HTML element
swiper.defaults
SwiperOptions
Swiper default options
swiper.extendedDefaults
SwiperOptions
Object with global Swiper extended 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:
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:
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.disable()
Disable Swiper (if it was enabled). When Swiper is disabled, it will hide all navigation elements and won't respond to any events and interactions
swiper.emit(event, args)
Fire event on instance
swiper.enable()
Enable Swiper (if it was disabled)
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:
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.
swiper.setGrabCursor()
Set grab cursor
swiper.setProgress(progress, speed)
Set Swiper translate progress (from 0 to 1). Where 0 - its initial position (offset) on first slide, and 1 - its maximum position (offset) on last slide
progress - number - Swiper translate progress (from 0 to 1).
speed - number - Transition duration (in ms).
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:
Using
onparameter on swiper initialization:
2. Using on method after swiper initialization.
Please note, that this keyword within event handler always points to Swiper instance
Name
Arguments
Description
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.
lock
(swiper)
Event will be fired when swiper is locked (when watchOverflow enabled)
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.
unlock
(swiper)
Event will be fired when swiper is unlocked (when watchOverflow enabled)
update
(swiper)
Event will be fired after swiper.update() call
Modules
Navigation
Navigation Parameters
Name
Type
Default
Description
navigation
boolean | NavigationOptions
Object with navigation parameters or boolean true to enable with default settings.
{
disabledClass
string
'swiper-button-disabled'
CSS class name added to navigation button when it becomes disabled
hiddenClass
string
'swiper-button-hidden'
CSS class name added to navigation button when it becomes hidden
hideOnClick
boolean
false
Toggle navigation buttons visibility after click on Slider's container
lockClass
string
'swiper-button-lock'
CSS class name added to navigation button when it is disabled
nextEl
HTMLElement | CSSSelector
null
String with CSS selector or HTML element of the element that will work like "next" button after click on it
prevEl
HTMLElement | CSSSelector
null
String with CSS selector or HTML element of the element that will work like "prev" button after click on it
}
Navigation Methods
Properties
swiper.navigation.nextEl
HTMLElement
HTMLElement of "next" navigation button
swiper.navigation.prevEl
HTMLElement
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)
Navigation Events
Name
Arguments
Description
navigationHide
(swiper)
Event will be fired on navigation hide
navigationShow
(swiper)
Event will be fired on navigation show
Pagination
Pagination Parameters
Name
Type
Default
Description
pagination
boolean | PaginationOptions
Object with pagination parameters or boolean true to enable with default settings.
{
bulletActiveClass
string
'swiper-pagination-bullet-active'
CSS class name of currently active pagination bullet
bulletClass
string
'swiper-pagination-bullet'
CSS class name of single pagination bullet
bulletElement
string
'span'
Defines which HTML tag will be used to represent single pagination bullet. Only for 'bullets' pagination type.
clickable
boolean
false
If true then clicking on pagination button will cause transition to appropriate slide. Only for bullets pagination type
clickableClass
string
'swiper-pagination-clickable'
CSS class name set to pagination when it is clickable
currentClass
string
'swiper-pagination-current'
CSS class name of the element with currently active index in "fraction" pagination
dynamicBullets
boolean
false
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.
dynamicMainBullets
number
1
The number of main bullets visible when dynamicBullets enabled.
el
HTMLElement | CSSSelector
null
String with CSS selector or HTML element of the container with pagination
formatFractionCurrent
function(number)
formatFractionTotal
function(number)
hiddenClass
string
'swiper-pagination-hidden'
CSS class name of pagination when it becomes inactive
hideOnClick
boolean
true
Toggle (hide/show) pagination container visibility after click on Slider's container
lockClass
string
'swiper-pagination-lock'
CSS class name set to pagination when it is disabled
modifierClass
string
'swiper-pagination-'
The beginning of the modifier CSS class name that will be added to pagination depending on parameters
progressbarFillClass
string
'swiper-pagination-progressbar-fill'
CSS class name of pagination progressbar fill element
progressbarOpposite
boolean
false
Makes pagination progressbar opposite to Swiper's direction parameter, means vertical progressbar for horizontal swiper direction and horizontal progressbar for vertical swiper direction
progressbarOppositeClass
string
'swiper-pagination-progressbar-opposite'
CSS class name of pagination progressbar opposite
renderBullet
function(index, className)
renderCustom
function(swiper, current, total)
renderFraction
function(currentClass, totalClass)
renderProgressbar
function(progressbarFillClass)
totalClass
string
'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.el
HTMLElement
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
Name
Arguments
Description
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
Name
Type
Default
Description
scrollbar
boolean | ScrollbarOptions
Object with scrollbar parameters or boolean true to enable with default settings.
{
dragClass
string
'swiper-scrollbar-drag'
Scrollbar draggable element CSS class
dragSize
number | 'auto'
'auto'
Size of scrollbar draggable element in px
draggable
boolean
false
Set to true to enable make scrollbar draggable that allows you to control slider position
el
HTMLElement | CSSSelector
null
String with CSS selector or HTML element of the container with scrollbar.
hide
boolean
true
Hide scrollbar automatically after user interaction
lockClass
string
'swiper-scrollbar-lock'
Scrollbar element additional CSS class when it is disabled
snapOnRelease
boolean
false
Set to true to snap slider position to slides when you release scrollbar
}
Scrollbar Methods
Properties
swiper.scrollbar.dragEl
HTMLElement
HTMLElement of Scrollbar draggable handler element
swiper.scrollbar.el
HTMLElement
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
Name
Arguments
Description
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
Name
Type
Default
Description
autoplay
boolean | AutoplayOptions
Object with autoplay parameters or boolean true to enable with default settings
{
delay
number
3000
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.
disableOnInteraction
boolean
true
Set to false and autoplay will not be disabled after user interactions (swipes), it will be restarted every time after interaction
pauseOnMouseEnter
boolean
false
When enabled autoplay will be paused on mouse enter over Swiper container. If disableOnInteraction is also enabled, it will stop autoplay instead of pause
reverseDirection
boolean
false
Enables autoplay in reverse direction
stopOnLastSlide
boolean
false
Enable this parameter and autoplay will be stopped when it reaches last slide (has no effect in loop mode)
waitForTransition
boolean
true
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.running
boolean
Whether autoplay enabled and running
Methods
swiper.autoplay.start()
Start autoplay
swiper.autoplay.stop()
Stop autoplay
Autoplay Events
Name
Arguments
Description
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 backgroundsSlides 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 directiondata-swiper-parallax-y- same but for y-axis directiondata-swiper-parallax-scale- scale ratio of the parallax element when it is in "inactive" (not on active slide) statedata-swiper-parallax-opacity- opacity of the parallax element when it is in "inactive" (not on active slide) statedata-swiper-parallax-duration- custom transition duration for parallax elements
Parallax Parameters
Name
Type
Default
Description
parallax
boolean | ParallaxOptions
Object with parallax parameters or boolean true to enable with default settings.
{
enabled
boolean
false
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:
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:
Or white one for dark layout:
After that we need to enable lazy loading on Swiper initialization:
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
Name
Type
Default
Description
lazy
boolean | LazyOptions
Enables images lazy loading. Object with lazy loading parameters or boolean true to enable with default settings
{
checkInView
boolean
false
Enables to check is the Swiper in view before lazy loading images on initial slides
elementClass
string
'swiper-lazy'
CSS class name of lazy element
loadOnTransitionStart
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
loadPrevNext
boolean
false
Set to true to enable lazy loading for the closest slides images (for previous and next slide images)
loadPrevNextAmount
number
1
Amount of next/prev slides to preload lazy images in. Can't be less than slidesPerView
loadedClass
string
'swiper-lazy-loaded'
CSS class name of lazy loaded element
loadingClass
string
'swiper-lazy-loading'
CSS class name of lazy loading element
preloaderClass
string
'swiper-lazy-preloader'
CSS class name of lazy preloader
scrollingElement
HTMLElement | CSSSelector | Dom7Array
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
Name
Arguments
Description
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
Name
Type
Default
Description
fadeEffect
FadeEffectOptions
Object with Fade-effect parameters
{
crossFade
boolean
false
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
Name
Type
Default
Description
coverflowEffect
CoverflowEffectOptions
Object with Coverflow-effect parameters.
{
depth
number
100
Depth offset in px (slides translate in Z axis)
modifier
number
1
Effect multiplier
rotate
number
50
Slide rotate in degrees
slideShadows
boolean
true
Enables slides shadows
stretch
number
0
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
Name
Type
Default
Description
flipEffect
FlipEffectOptions
Object with Flip-effect parameters
{
limitRotation
boolean
true
Limit edge slides rotation
slideShadows
boolean
true
Enables slides shadows
}
Cube Effect
Be sure to have the effect param set to 'cube' in order for this to work.
Cube Effect Parameters
Name
Type
Default
Description
cubeEffect
CubeEffectOptions
Object with Cube-effect parameters
{
shadow
boolean
true
Enables main slider shadow
shadowOffset
number
20
Main shadow offset in px
shadowScale
number
0.94
Main shadow scale ratio
slideShadows
boolean
true
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
Name
Type
Default
Description
thumbs
ThumbsOptions
Object with thumbs component parameters
{
autoScrollOffset
number
0
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
multipleActiveThumbs
boolean
true
When enabled multiple thumbnail slides may get activated
slideThumbActiveClass
string
'swiper-slide-thumb-active'
Additional class that will be added to activated thumbs swiper slide
swiper
Swiper
null
Swiper instance of swiper used as thumbs or object with Swiper parameters to initialize thumbs swiper
thumbsContainerClass
string
'swiper-container-thumbs'
Additional class that will be added to thumbs swiper-container
}
Thumbs Methods
Properties
swiper.thumbs.swiper
Swiper
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:
All "zoomable" images should be wrapped with the div with
swiper-zoom-containerclass.By default it expects to zoom one of the
img,pictureorcanvaselement. If you want to make zoom on some other custom element, then just addswiper-zoom-targetclass to this element. For example:
You can override
maxRatioparameter for specific slides by usingdata-swiper-zoomattribute on zoom container.
Zoom Parameters
Name
Type
Default
Description
zoom
boolean | ZoomOptions
Enables zooming functionality. Object with zoom parameters or boolean true to enable with default settings
{
containerClass
string
'beae-swiper-zoom-container'
CSS class name of zoom container
maxRatio
number
3
Maximum image zoom multiplier
minRatio
number
1
Minimal image zoom multiplier
toggle
boolean
true
Enable/disable zoom-in by slide's double tap
zoomedSlideClass
string
'beae-swiper-slide-zoomed'
CSS class name of zoomed in container
}
Zoom Methods
Properties
swiper.zoom.enabled
boolean
Whether the zoom module is enabled
swiper.zoom.scale
number
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
Name
Arguments
Description
zoomChange
(swiper, scale, imageEl, slideEl)
Event will be fired on zoom change
Keyboard Control
Keyboard Control Parameters
Name
Type
Default
Description
keyboard
boolean | KeyboardOptions
Enables navigation through slides using keyboard. Object with keyboard parameters or boolean true to enable with default settings
{
enabled
boolean
false
Set to true to enable keyboard control
onlyInViewport
boolean
true
When enabled it will control sliders that are currently in viewport
pageUpDown
boolean
true
When enabled it will enable keyboard navigation by Page Up and Page Down keys
}
Keyboard Control Methods
Properties
swiper.keyboard.enabled
boolean
Whether the keyboard control is enabled
Methods
swiper.keyboard.disable()
Disable keyboard control
swiper.keyboard.enable()
Enable keyboard control
Keyboard Events
Name
Arguments
Description
keyPress
(swiper, keyCode)
Event will be fired on key press
Mousewheel Control
Mousewheel Control Parameters
Name
Type
Default
Description
mousewheel
boolean | MousewheelOptions
Enables navigation through slides using mouse wheel. Object with mousewheel parameters or boolean true to enable with default settings
{
eventsTarget
'container' | HTMLElement | CSSSelector | 'wrapper'
'container'
String with CSS selector or HTML element of the container accepting mousewheel events. By default it is swiper-container
forceToAxis
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.
invert
boolean
false
Set to true to invert sliding direction
releaseOnEdges
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)
sensitivity
number
1
Multiplier of mousewheel data, allows to tweak mouse wheel sensitivity
thresholdDelta
number
null
Minimum mousewheel scroll delta to trigger swiper slide change
thresholdTime
number
null
Minimum mousewheel scroll time delta (in ms) to trigger swiper slide change
}
Mousewheel Control Methods
Properties
swiper.mousewheel.enabled
boolean
Whether the mousewheel control is enabled
Methods
swiper.mousewheel.disable()
Disable mousewheel control
swiper.mousewheel.enable()
Enable mousewheel control
Mousewheel Events
Name
Arguments
Description
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
Name
Type
Default
Description
virtual
boolean | VirtualOptions
Enables virtual slides functionality. Object with virtual slides parameters or boolean true to enable with default settings.
{
addSlidesAfter
number
0
Increases amount of pre-rendered slides after active slide
addSlidesBefore
number
0
Increases amount of pre-rendered slides before active slide
cache
boolean
true
Enables DOM cache of rendering slides html elements. Once they are rendered they will be saved to cache and reused from it.
renderExternal
function(data)
renderExternalUpdate
boolean
true
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
renderSlide
function(slide, index)
slides
any[]
[]
Array with slides
}
Virtual Slides Methods
Properties
swiper.virtual.cache
object
Object with cached slides HTML elements
swiper.virtual.from
number
Index of first rendered slide
swiper.virtual.slides
Array with slide items passed by virtual.slides parameter
swiper.virtual.to
number
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 virtual slides state
Controller
Controller Parameters
Name
Type
Default
Description
controller
ControllerOptions
Object with controller parameters or boolean true to enable with default settings
{
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).
control
Swiper | Swiper[]
Pass here another Swiper instance or array with Swiper instances that should be controlled by this Swiper
inverse
boolean
false
Set to true and controlling will be in inverse direction
}
Controller Methods
Properties
swiper.controller.control
Swiper
Pass here another Swiper instance or array with Swiper instances that should be controlled by this Swiper
Accessibility (a11y)
Accessibility Parameters
Name
Type
Default
Description
a11y
A11yOptions
Object with a11y parameters or boolean true to enable with default settings.
{
containerMessage
string
null
Message for screen readers for outer swiper container
containerRoleDescriptionMessage
string
null
Message for screen readers describing the role of outer swiper container
enabled
boolean
true
Enables A11y
firstSlideMessage
string
'This is the first slide'
Message for screen readers for previous button when swiper is on first slide
itemRoleDescriptionMessage
string
null
Message for screen readers describing the role of slide element
lastSlideMessage
string
'This is the last slide'
Message for screen readers for next button when swiper is on last slide
nextSlideMessage
string
'Next slide'
Message for screen readers for next button
notificationClass
string
'swiper-notification'
CSS class name of A11y notification
paginationBulletMessage
string
'Go to slide {{index}}'
Message for screen readers for single pagination bullet
prevSlideMessage
string
'Previous slide'
Message for screen readers for previous button
slideLabelMessage
string
'{{index}} / {{slidesLength}}'
Message for screen readers describing the label of slide element
slideRole
string
'group'
Value of swiper slide role attribute
}
If you use bundler with JS modules support in your project you can import only the modules you need:
The following modules are exported:
Swiper- core libraryVirtual- Virtual Slides moduleNavigation- Navigation modulePagination- Pagination moduleScrollbar- Scrollbar moduleParallax- Parallax moduleLazy- Lazy moduleController- Controller moduleA11y- Accessibility moduleAutoplay- Autoplay moduleEffectFade- Fade Effect moduleEffectCube- Cube Effect moduleEffectFlip- Flip Effect moduleEffectCoverflow- Coverflow Effect moduleThumbs- Thumbs module
Last updated