Getting Started

You're browsing the documentation for v3

Installation

You have 4 options to include Splide on your site.

NPM

The recommended installation method is NPM. Install the latest version by the following command:

$ npm install @splidejs/splide

Hosting Files

You can download the Splide package from the following link:

Download

Go to the dist/js directory, and import the splide.min.js file by the <script> tag:

<script src="path-to-the-file/splide.min.js"></script>
HTML

CDN

You can also include this library from CDN:

jsDelivr

For production, I recommend using a specific version number instead of the "latest" keyword to avoid unexpected breakage from the further update.

Integration

Integration packages are available for React, Vue and Svelte.

The latest version only supports Vue 3. You have to use the old version (0.3.5) for Vue 2, but the Splide version is also outdated.

Importing CSS

Secondly, select the CSS file and link it to your site.

Files

You will see several CSS files in the dist/css and dist/css/themes directories.

FileDescription
splide.min.cssIncludes all styles. The content is same with splide-default.min.css
splide-[theme].min.cssIncludes all styles
splide-core.min.cssIncludes only core styles

If you want to fully customize the slider appearance, pick the splide-core.min.css file that does not include arrows, pagination and progress bar styles, which reduces unnecessary "override" works. Otherwise, select splide.min.css or splide-[theme].min.css.

Linking The Style Sheet

Once select a theme, link to the file by the <link> element.

<!-- Link to the file hosted on your server, -->
<link rel="stylesheet" href="path-to-the-file/splide.min.css">
<!-- or link to the CDN -->
<link rel="stylesheet" href="url-to-cdn/splide.min.css">
HTML

HTML

Next, write the required markup to build your slider.

Basic Structure

This is the basic HTML structure that Splide requires:

<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>
</ul>
</div>
</div>
HTML

Insert any contents inside .splide__slide elements such as images and texts. You can use <div> element instead of <ul> and <li>, but they should be a list element in terms of semantic markup.

When you create an image slider, the cover option is useful. It converts all images to the background-image of each parent element. That means you don't have to crop images by your image editor.

Additional HTML

You may need to add more HTML markups in following cases:

  • Using custom arrows
  • Adding a progress bar or play/pause buttons for autoplay

See Arrows, Autoplay, or Structure for more details.

Applying Splide

Finally, apply Splide to your HTML element.

Using Import

Import the Splide class, instantiate it, and call the mount() method. The first argument of the constructor accepts a CSS selector, or an element itself.

import Splide from '@splidejs/splide';
new Splide( '.splide' ).mount();
JavaScript

Do not forget to call mount() method, or nothing will appear in the browser.

Using The Global Class

If you include the library via the <script> tag, you can globally access the Splide class.

<script>
new Splide( '.splide' ).mount();
</script>
HTML

Make sure the target element is loaded before constructing the Splide instance.

<script>
document.addEventListener( 'DOMContentLoaded', function() {
var splide = new Splide( '.splide' );
splide.mount();
} );
</script>
HTML

Multiple Sliders

Each Splide instance can create only one slider. Even if you pass a class name to the constructor, Splide applies the slider to only the first matched element. If you want to build multiple sliders, create same number of instances respectively.

new Splide( '#slider1' ).mount();
new Splide( '#slider2' ).mount();
new Splide( '#slider3' ).mount();
JavaScript

Or you can initialize them by the for loop:

var elms = document.getElementsByClassName( 'splide' );
for ( var i = 0; i < elms.length; i++ ) {
new Splide( elms[ i ] ).mount();
}
JavaScript