Full-featured Slider/Carousel Plugin – Splide

---

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).