> For the complete documentation index, see [llms.txt](https://docs.beae.dev/beae-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.beae.dev/beae-docs/developer/vendors/slider.md).
# 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
```javascript
{
computed:{
vendors(){
return ['slider_js','slider_css'];
}
}
}
```
{% tabs %}
{% tab title="Javascript" %}
```javascript
{
javascript(){
return function(){
var $el = this.$el,
$selector = $el.querySelector('.beae-swiper-container'),
$pagination = $el.querySelector('.beae-swiper-pagination'),
$next = $el.querySelector('.beae-swiper-button-next'),
$prev = $el.querySelector('.beae-swiper-button-prev'),
$scrollbar = $el.querySelector('.beae-swiper-scrollbar')
const swiper = new BeaeSwiper($selector, {
// Optional parameters
loop: true,
// If we need pagination
pagination: {
el: $pagination,
},
// Navigation arrows
navigation: {
nextEl: $next,
prevEl: $prev,
},
// And if we need scrollbar
scrollbar: {
el: $scrollbar,
},
});
}
}
}
```
{% endtab %}
{% tab title="HTML" %}
```markup
Slide 1
Slide 2
Slide 3
...
```
{% endtab %}
{% endtabs %}
## 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:
```javascript
const swiper = this.$el.querySelector('.beae-swiper-container').swiper;
// Now you can use all slider methods like
swiper.slideNext();
```
### 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
speed parameter will have no effect- All transition start/end related events (use
slideChange instead) slidesPerGroup has limited supportcenteredSlides is not supported- Changing slides with anything except touch/swipe and mousewheel will happen without transition in browsers without
scrollTo.behaviour = 'smooth' support (e.g. in desktop and iOS Safari) simulateTouch doesn't have effect and "dragging" with mouse doesn't workresistance doesn't have any effectallowSlidePrev/NextswipeHandlerfreeMode and 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:
1. Using `on` parameter on swiper initialization:
```javascript
const swiper = new window.BeaeSwiper('.beae-swiper-container', {
// ...
on: {
init: function () {
console.log('swiper initialized');
},
},
});
```
2\. Using `on` method after swiper initialization.
```javascript
const swiper = new window.BeaeSwiper('.beae-swiper-container', {
// ...
});
swiper.on('slideChange', function () {
console.log('slide changed');
});
```
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 backgrounds
* Slides child elements. Parallax effect for such elements will depend on slide progress
To enable parallax effects you need to init Swiper with passed `parallax:true` parameter and add one of the following (or mix) attributes to required elements:
* `data-swiper-parallax` - enable transform-translate parallax transition. This attribute may accept:
* `number` - value in px (as for title, subtitle in example above) to move element depending on progress. In this case such element will be moved on ± this value in px depending on slide position (next or previous)
* `percentage` - (as for "parallax-bg") to move element depending on progress and on its size. In this case such element will be moved on ± this percentage of its size (width in horizontal direction, and height in vertical direction) depending on slide position (next or previous). So if element has 400px width and you specified data-swiper-parallax="50%" then it will be moved on ± 200px
* `data-swiper-parallax-x` - same but for x-axis direction
* `data-swiper-parallax-y` - same but for y-axis direction
* `data-swiper-parallax-scale` - scale ratio of the parallax element when it is in "inactive" (not on active slide) state
* `data-swiper-parallax-opacity` - opacity of the parallax element when it is in "inactive" (not on active slide) state
* `data-swiper-parallax-duration` - custom transition duration for parallax elements
```markup
Slide 1
Subtitle
Lorem ipsum dolor sit amet, ...
I will change opacity
I will change scale
...
```
**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:
```markup
```
As you see:
* Each lazy loaded image/element should have additional "swiper-lazy" class
* Lazy image source for \![]()
element should be specified in "data-src" attribute instead of "src"
* Lazy image source set for \![]()
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:
```markup
```
Or white one for dark layout:
```
```
After that we need to enable lazy loading on Swiper initialization:
```javascript
const swiper = new BeaeSwiper('.beae-swiper-container', {
// Disable preloading of all images
preloadImages: false,
// Enable lazy loading
lazy: true,
});
```
If you use `slidesPerView: 'auto'` or `slidesPerView > 1`, then you should also enable `watchSlidesVisibility` and Swiper will load images in currently visible slides
**Lazy Loading Parameters**
| 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](https://swiperjs.com/swiper-api#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:
```markup
```
* All "zoomable" images should be wrapped with the div with `swiper-zoom-container` class.
* By default it expects to zoom one of the `img`, `picture` or `canvas` element. If you want to make zoom on some other custom element, then just add `swiper-zoom-target` class to this element. For example:
```markup
```
* You can override `maxRatio` parameter for specific slides by using `data-swiper-zoom` attribute 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 library
* `Virtual` - Virtual Slides module
* `Navigation` - Navigation module
* `Pagination` - Pagination module
* `Scrollbar` - Scrollbar module
* `Parallax` - Parallax module
* `Lazy` - Lazy module
* `Controller` - Controller module
* `A11y` - Accessibility module
* `Autoplay` - Autoplay module
* `EffectFade` - Fade Effect module
* `EffectCube` - Cube Effect module
* `EffectFlip` - Flip Effect module
* `EffectCoverflow` - Coverflow Effect module
* `Thumbs` - Thumbs module
