Getting Started

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.

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 carousel 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

Or import files if your bundler supports CSS:

// Default theme
import '@splidejs/splide/css';
// or other themes
import '@splidejs/splide/css/skyblue';
import '@splidejs/splide/css/sea-green';
// or only core styles
import '@splidejs/splide/css/core';
JavaScript

HTML

Next, build your carousel with HTML.

We have two basic structures that depend on whether the carousel is directly related to your main contents or not. If it is — e.g. banners, gallery, cards, or list of products — use the following markup:

<section class="splide" aria-label="Splide Basic HTML Example">
<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>
</section>
HTML

If not, meaning your carousel is not relevant to your main contents or just for decoration, use this markup:

<div class="splide" role="group" aria-label="Splide Basic HTML Example">
<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> in lieu of <section>, <ul> and <li>.

In any structures, make sure to provide a concise label to the root element. If you have a visible label for the carousel, associate it to your carousel via aria-labelledby instead of aria-label:

<section class="splide" aria-labelledby="carousel-heading">
<h2 id="carousel-heading">Splide Basic HTML Example</h2>
<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>
</section>
HTML

Visit this page 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 has been loaded before constructing the Splide instance. You'll need to subscribe a DOMContentLoaded event if you initialize it in a <head> tag:

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

Multiple carousels

Each Splide instance can create only one carousel. Even if you pass a class name to the constructor, Splide applies the carousel to only the first matched element. If you want to build multiple carousels, 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