Author: | Splidejs |
---|---|
Views Total: | 631 views |
Official Page: | Go to website |
Last Update: | December 1, 2020 |
License: | MIT |
Preview:

Description:
Splide is a lightweight, responsive, accessible, mobile-friendly, full-featured slider/carousel plugin implemented in pure JavaScript and CSS/CSS3.
More features:
- Touch-enabled. Supports both touch swipe and mouse drag.
- Smooth slide & fade transitions based on CSS3.
- Image lazy loading.
- Supports nested sliders.
- Supports HTML video, YouTube or Vimeo videos.
- Allows multiple items on a slide.
- Autoplay.
- URL hash change.
- RTL mode.
- Horizontal and vertical directions.
Basic usage:
Install and import the Splide library.
# Core $ npm install @splidejs/splide --save # Video Extension $ npm install @splidejs/splide-extension-video --save # URL Hash Change Extension $ npm install @splidejs/splide-extension-url-hash --save
// Core import splide from '@splidejs/splide'; // Video Extension import Video from '@splidejs/splide-extension-video'; // URL Hash Change Extension import URLHash from '@splidejs/splide-extension-url-hash';
Alternatively, you can directly load the necessary JavaScript and CSS files in the document.
<!-- Core --> <link rel="stylesheet" href="dist/css/splide.min.css"> <script src="dist/js/splide.min.js"></script> <!-- Video Extension --> <link rel="stylesheet" href="splide-extension-video/dist/css/splide-extension-video.min.css"> <script src="splide-extension-video/dist/js/splide-extension-video.min.js"></script> <!-- URL Hash Change Extension --> <script src="splide-extension-url-hash/dist/js/splide-extension-url-hash.min.js"></script>
Insert any content as slides to the slider.
<div class="splide"> <div class="splide__track"> <ul class="splide__list"> <li class="splide__slide">Slide 01</li> <li class="splide__slide">Slide 02</li> <li class="splide__slide">Slide 03</li> <li class="splide__slide">Slide 04</li> <li class="splide__slide">Slide 05</li> </ul> </div> </div>
<div class="splide"> <div class="splide__track"> <ul class="splide__list"> <li class="splide__slide"> <div class="splide__slide__container"> <img src="1.jpg"> </div> Slide 1 </li> <li class="splide__slide"> <div class="splide__slide__container"> <img src="2.jpg"> </div> Slide 2 </li> <li class="splide__slide"> <div class="splide__slide__container"> <img src="3.jpg"> </div> Slide 3 </li> </ul> </div> </div>
You might need a progress bar on the Autoplay mode that indicates the time to wait before transitioning to the next slide.
<div class="splide__progress"> <div class="splide__progress__bar"> </div> </div>
Invoke the slider plugin with default options. That’s it.
new Splide( '.splide' ).mount();
Create a video carousel using the Video extension.
<div class="splide"> <div class="splide__track"> <ul class="splide__list"> <li class="splide__slide" data-splide-youtube="YOUTUBE VIDEO URL"> <img src="cover.jpg"> </li> <li class="splide__slide" data-splide-vimeo="VIMEO VIDEO URL"> <img src="cover.jpg"> </li> </ul> </div> </div>
new Splide( '#splide', { video: { // options here }, }).mount(window.splide.Extensions);
Enable the URL hash change extension.
<div class="splide"> <div class="splide__track"> <ul class="splide__list"> <li class="splide__slide" data-splide-hash="slide01"></li> <li class="splide__slide" data-splide-hash="slide02"></li> <li class="splide__slide" data-splide-hash="slide03"></li> </ul> </div> </div>
new Splide( '#splide' ).mount(window.splide.Extensions);
All possible options to customize the slider.
new Splide( '.splide' , { /** * Determine a slider type. * - 'slide': Regular slider. * - 'loop' : Carousel slider. * - 'fade' : Change slides with fade transition. perPage, drag options are ignored. * * @type {string} */ type: 'slide', /** * Whether to rewind a slider before the first slide or after the last one. * In "loop" mode, this option is ignored. * * @type {boolean} */ rewind: false, /** * Transition speed in milliseconds. * * @type {number} */ speed: 400, /** * Transition speed on rewind in milliseconds. * * @type {number} */ rewindSpeed: 0, /** * Whether to prevent any actions while a slider is transitioning. * If false, navigation, drag and swipe work while the slider is running. * Even so, it will be forced to wait for transition in some cases in the loop mode to shift a slider. * * @type {boolean} */ waitForTransition: true, /** * Define slider max width. * * @type {number} */ width: 0, /** * Define slider height. * * @type {number} */ height: 0, /** * Fix width of slides. CSS format is allowed such as 10em, 80% or 80vw. * perPage number will be ignored when this option is falsy. * * @type {number|string} */ fixedWidth: 0, /** * Fix height of slides. CSS format is allowed such as 10em, 80vh but % unit is not accepted. * heightRatio option will be ignored when this option is falsy. * * @type {number} */ fixedHeight: 0, /** * Determine height of slides by ratio to a slider width. * This will be ignored when the fixedHeight is provided. * * @type {number} */ heightRatio: 0, /** * If true, slide width will be determined by the element width itself. * - perPage/perMove should be 1. * - lazyLoad should be false. * * @type {boolean} */ autoWidth: false, /** * Determine how many slides should be displayed per page. * * @type {number} */ perPage: 1, /** * Determine how many slides should be moved when a slider goes to next or perv. * * @type {number} */ perMove: 0, /** * Start index. * * @type {number} */ start: 0, /** * Determine manually how many clones should be generated on the left and right side. * The total number of clones will be twice of this number. * * @type {number} */ clones: 0, /** * Determine which slide should be focused if there are multiple slides in a page. * A string "center" is acceptable for centering slides. * * @type {boolean|number|string} */ focus: false, /** * Gap between slides. CSS format is allowed such as 1em. * * @type {number|string} */ gap: 0, /** * Set padding-left/right in horizontal mode or padding-top/bottom in vertical one. * Give a single value to set a same size for both sides or * do an object for different sizes. * Also, CSS format is allowed such as 1em. * * @example * - 10: Number * - '1em': CSS format. * - { left: 0, right: 20 }: Object for different sizes in horizontal mode. * - { top: 0, bottom: 20 }: Object for different sizes in vertical mode. * * @type {number|string|Object} */ padding: 0, /** * Whether to append arrows. * * @type {boolean} */ arrows: true, /** * Change the arrow SVG path like 'm7.61 0.807-2.12...'. * * @type {string} */ arrowPath: '', /** * Whether to append pagination(indicator dots) or not. * * @type {boolean} */ pagination: true, /** * Activate autoplay. * * @type {boolean} */ autoplay: false, /** * Autoplay interval in milliseconds. * * @type {number} */ interval: 5000, /** * Whether to stop autoplay when a slider is hovered. * * @type {boolean} */ pauseOnHover: true, /** * Whether to stop autoplay when a slider elements are focused. * True is recommended for accessibility. * * @type {boolean} */ pauseOnFocus: true, /** * Whether to reset progress of the autoplay timer when resumed. * * @type {boolean} */ resetProgress: true, /** * Loading images lazily. * Image src must be provided by a data-splide-lazy attribute. * * - false: Do nothing. * - 'nearby': Only images around an active slide will be loaded. * - 'sequential': All images will be sequentially loaded. * * @type {boolean|string} */ lazyLoad: false, /** * This option works only when a lazyLoad option is "nearby". * Determine how many pages(not slides) around an active slide should be loaded beforehand. * * @type {number} */ preloadPages: 1, /** * Easing for CSS transition. For example, linear, ease or cubic-bezier(). * * @type {string} */ easing: 'cubic-bezier(.42,.65,.27,.99)', /** * Whether to control a slide via keyboard. * * @type {boolean} */ keyboard: true, /** * Whether to allow mouse drag and touch swipe. * * @type {boolean} */ drag: true, /** * The angle threshold for drag. * The slider starts moving only when the drag angle is less than this threshold. * * @type {number} */ dragAngleThreshold: 30, /** * Distance threshold for determining if the action is "flick" or "swipe". * When a drag distance is over this value, the action will be treated as "swipe", not "flick". * * @type {number} */ swipeDistanceThreshold: 150, /** * Velocity threshold for determining if the action is "flick" or "swipe". * Around 0.5 is recommended. * * @type {number} */ flickVelocityThreshold: .6, /** * Determine power of flick. The larger number this is, the farther a slider runs by flick. * Around 500 is recommended. * * @type {number} */ flickPower: 600, /** * Limit a number of pages to move by flick. * * @type {number} */ flickMaxPages: 1, /** * Slider direction. * - 'ltr': Left to right. * - 'rtl': Right to left. * - 'ttb': Top to bottom. * * @type {string} */ direction: 'ltr', /** * Set img src to background-image of its parent element. * Images with various sizes can be displayed as same dimension without cropping work. * fixedHeight or heightRatio is required. * * @type {boolean} */ cover: false, /** * Whether to enable accessibility(aria and screen reader texts) or not. * * @type {boolean} */ accessibility: true, /** * Whether to add tabindex="0" to visible slides or not. * * @type {boolean} */ slideFocus: true, /** * Determine if a slider is navigation for another. * Use "sync" API to synchronize two sliders. * * @type {boolean} */ isNavigation: false, /** * Whether to trim spaces before the fist slide or after the last one when "focus" is not 0. * * @type {boolean} */ trimSpace: true, /** * Slide status is updated after move as default. * If true, it will be updated before move. * * @type {boolean} */ updateOnMove: false, /** * Throttle duration in milliseconds for the resize event. * * @type {number} */ throttle: 100, /** * Breakpoints definitions. * * @example * { * '1000': { * perPage: 3, * gap: 20 * }, * '600': { * perPage: 1, * gap: 5, * } * } * * @type {boolean|Object} */ breakpoints: false, /** * Collection of class names. * * @see ./classes.js * * @type {Object} */ classes: ELEMENT_CLASSES, /** * Collection of i18n texts. * * @see ./i18n.js * * @type {Object} */ i18n: I18N }).mount();
Possible options for the video extension.
new Splide( '.splide' , { video: { /** * Whether to play the video automatically. * * @type {boolean} */ autoplay: false, /** * Hide the video control UI. * * @type {boolean} */ hideControls: false, /** * Hide full screen button. * Only for YouTube. * * @type {boolean} */ disableFullScreen: false, /** * Loop the video. * * @type {boolean} */ loop: false, /** * Mute the video. * * @type {boolean} */ mute: false, /** * Default volume(0.0-1.0). * * @type {number} */ volume: 0.2 } })
You can also pass the options via HTML data attributes as follows:
<div class="splide" data-splide="{OPTIONS HERE}"> </div>
Event listeners.
instance.on( 'mounted', function () { // do something }); instance.on( 'updated', function (OPTIONS) { // do something }); instance.on( 'move', function (newIndex, oldIndex, destIndex) { // do something }); instance.on( 'moved', function (newIndex, oldIndex, destIndex) { // do something }); instance.on( 'drag', function (info) { // do something }); instance.on( 'dragged', function (info) { // do something }); instance.on( 'visible', function (slideObject) { // do something }); instance.on( 'hidden', function (slideObject) { // do something }); instance.on( 'active', function (slideObject) { // do something }); instance.on( 'inactive', function (slideObject) { // do something }); instance.on( 'click', function (slideObject) { // do something }); instance.on( 'arrows:mounted', function (prev, next) { // do something }); instance.on( 'arrows:updated', function (prev, next, prevIndex, nextIndex) { // do something }); instance.on( 'pagination:mounted', function (data, activeItem:) { // do something }); instance.on( 'pagination:updated', function (data, prevItem, nextItem) { // do something }); instance.on( 'navigation:mounted', function (Splide) { // do something }); instance.on( 'autoplay:play', function () { // do something }); instance.on( 'autoplay:pause', function () { // do something }); instance.on( 'autoplay:playing', function () { // do something }); instance.on( 'lazyload:loaded', function () { // do something }); instance.on( 'video:play', function (player) { // do something }); instance.on( 'video:paused', function (player) { // do something }); instance.on( 'video:ended', function (player) { // do something });
Properties.
// root element splide.root // zero-based active index splide.index // options splide.options // the number of slides splide.length // a collection of CSS classes splide.classes // i18n splide.i18n // an object containing all components splide.Components // set/get state // CREATED = 1: Splide instance has just been created. // MOUNTED = 2: All components have been mounted. // IDLE = 3: Idling. // MOVING = 4: The slider is moving. splide.State.is( 4 ) splide.State.set( 2 )
API methods.
// go to a specific slide // {number}: Go to slide specified by {number}. // '+','+{number}': Increase active slide index. // '-','-{number}': Decrease active slide index. // '>','>{number}': Go to next page or the page specified by {number}. For example, '>2' moves a slider to page 2. // '<','<{number}': Go to previous page or the page specified by {number}. splide.go(0); // check the slider type // SLIDE = 'slide' // LOOP = 'loop' // FADE = 'fade' splide.is( 'loop' ); // register a Splide instance for sync // must be called before mount(). splide.sync( splide ); // add a new slide splide.add( slide, index ); // remove a slide splide.remove( index ); // refresh the slider splide.refresh(); // destroy the slider splide.destroy();
Changelog:
v2.4.21 (12/01/2020)
- Bug Fix
v2.4.20 (11/22/2020)
- Fixed: The last image missed is-visible class on zoom
v2.4.19 (11/21/2020)
- Fixed: is-visible class was sometimes not updated correctly
v2.4.18 (11/20/2020)
- Fixed: Autoplay progress was not reset when arrows were click
- Fixed: add() and remove() didn’t work correctly in loop mode
v2.4.15/16 (11/19/2020)
- Fixed: Minute drag prevents other child event listeners from firing
v2.4.14 (11/17/2020)
- Update dependencies.
v2.4.13 (08/30/2020)
- Bug Fix: Prevent click while dragging the slider in fade mode
v2.4.12 (08/24/2020)
- Fixed: Autoplay was not properly resumed on blur.
v2.4.11 (08/17/2020)
- Fixed: The track position was wrong in RTL mode.
- Fixed the invalid CSS property name.
v2.4.10 (07/30/2020)
- Fixed: Relative units(em, rem, etc) for the fixedWidth/fixedHeight option didn’t work.
v2.4.8 (07/26/2020)
- Bug Fix: mount() was called twice when destroy() and mount() were called manually, because of the breakpoint component.
v2.4.8 (07/17/2020)
- The Lazyload component accepts a srcset attribute
v2.4.6 (07/14/2020)
- Fixed Padding became undefined when the Splide instance was converted to JSON by JSON.stringify.
- Fixed Padding and gap were not updated correctly on resize if they were described by % or vw.
v2.4.4 (06/23/2020)
- Bugfix: Drag/swipe didn’t work correctly.
- Bugfix: Transition animation was skipped only in the first page of a RTL slider.
v2.4.3 (06/21/2020)
- Can select the target of the keyboard event from the document or the root element.
- Can remove tab indices from slides by slideFocus option.
- Can determine whether to prevent any actions while transitioning or not by the waitForTransition option.
- Change the way of the Layout calculation.
- Merge the horizontal and vertical sub components into the Track component.
v2.4.1 (06/20/2020)
- Optimization. Remove horizontal and vertical directions of the Track component.
v2.4.0 (06/17/2020)
- Support drag for the fade type.
v2.3.8 (06/05/2020)
- The number of clones can be determined by options.
- Fixed: Loop didn’t work well when fixedWidth is provided and number of slides is not enough to fill the view port.
v2.3.6 (05/31/2020)
- Fixed: invalid realIndex was assigned to a slide when the length of slides were less than perPage.
- Emit click event when a slide is clicked.
- All components will be evaluated again when the Splide is remounted.
v2.3.5 (05/29/2020)
- Bug Fix: Invalid realIndex was assigned to a slide when the length of slides were less than perPage.
v2.3.2 (05/28/2020)
- Bug Fix: perMove didn’t work properly with autoplay
v2.3.1 (05/21/2020)
- Bug Fix: The “is-active” class was not inserted the active slide when the updateOnMove option was true
v2.2.7 (05/17/2020)
- Breakpoints support “drag” and “pagination”.
- Throttle duration for the resize event can be changed through options.
v2.2.7 (05/05/2020)
- Bug Fix: Slide width was wrong when the window scrollbar was made hidden by the Layout component.
v2.2.6 (05/04/2020)
- Resolve a conflict with prototype.js.
v2.2.5 (04/30/2020)
- Support a hierarchical selector for initialization:
new Splide(".container .splide-container .splide");
- Fixed an error occurred when “destroy” was true and “arrows” was false.
v2.2.4 (04/15/2020)
- You can config the Thresholds for drag angle and swipe distance
- Remove the difference between splide.js and splide.min.js
v2.2.3 (03/25/2020)
- Added
type="button"
attribute to buttons of pagination and arrows
v2.2.1 (02/16/2020)
- Bug Fix: Window location was changed only in Safari when arrows or thumbnails were clicked
v2.2.0 (02/14/2020)
- Add some themes to change slider appearance.
v2.1.0 (02/13/2020)
- Bug Fix: Hide broken image icons.
v2.0.1 (02/07/2020)
- Auto Width is implemented. Each slide can have its own width.
- Breakpoints accept ‘destroy’ option.
- Merge Slides component to Elements.
v1.4.1 (02/01/2020)
- Splide can be destroyed.
- Add/remove slides dynamically by API.
v1.3.4 (01/12/2020)
- Expose state constants to access them from other scripts.
v1.3.3 (01/09/2020)
- Fixed: perMove was not updated according to the breakpoints option.
v1.3.2 (01/08/2020)
- Fixed version number
- Updated package.
v1.3.1 (12/20/2019)
- Add the updateOnMove option which changes the update timing of adding is-active/is-visible classes.
v1.2.7 (11/28/2019)
- Bug Fix: Arrows were not shown in fade mode because of z-index.
v1.2.5 (11/25/2019)
- Prevent propagation of click events during drag/swipe, even if listeners are added by script.
- Disable dragging anchors.
v1.2.4 (11/24/2019)
- Prevent dragging an image itself inside a slide.
- Add Links component that prevents clicking links(anchors) while a slide is dragged/swiped.
v1.2.3 (11/24/2019)
- Fix wrong comments(data-splide-src -> data-splide-lazy).
It looks great. But I cannot get it to advance however. Also, my splide list goes out past the width of my page and all pics are visible at the same time. I looked through options and tried many things… but I am about ready to give up. I followed examples from the Splide site exactly and they did not work for me.