Image Slider

You're browsing the documentation for v3

Introduction

The goal of this tutorial is to create a typical image slider with/without texts. This page also introduces how to crop images by the cover option. Let's start! 🧐

Basic Image Slider

First, put your images to slide elements:

<div id="image-slider" class="splide">
<div class="splide__track">
<ul class="splide__list">
<li class="splide__slide">
<img src="image01.jpg">
</li>
<li class="splide__slide">
<img src="image02.jpg">
</li>
<li class="splide__slide">
<img src="image03.jpg">
</li>
</ul>
</div>
</div>
HTML

To adapt the image width to each slide, add the following CSS.

.splide__slide img {
width: 100%;
height: auto;
}
CSS

And then, initialize Splide after the DOM content is loaded. You have to listen to the DOMContentLoaded event if you initialize it in the <head> tag:

<script>
document.addEventListener( 'DOMContentLoaded', function () {
new Splide( '#image-slider' ).mount();
} );
</script>
HTML

Or you don't have to if you do that on the end of the <body> tag:

<script>
new Splide( '#image-slider' ).mount();
</script>
HTML

Now we get the following slider:

  • Sample Slide 01
  • Sample Slide 02
  • Sample Slide 03

Auto Crop

Source images usually have different aspect ratios. Splide provides the way to crop images into same dimensions by the cover option that sets sources to their parent element as a background-image.

document.addEventListener( 'DOMContentLoaded', function () {
new Splide( '#image-slider', {
cover : true,
heightRatio: 0.5,
} ).mount();
} );
JavaScript

The result will be like this:

  • Sample Slide 01
  • Sample Slide 02
  • Sample Slide 03

Do not forget to provide the height, heightRatio or fixedHeight option to ensure the slide has explicit height.

If you do not have to support IE, you can use the object-fit property instead of the cover option.

Images and Texts

Splide accepts any content inside slides. It's very easy to create a card style slider:

<div id="image-slider" class="splide">
<div class="splide__track">
<ul class="splide__list">
<li class="splide__slide">
<img src="image01.jpg">
<div>
Description 01
</div>
</li>
<li class="splide__slide">
<img src="image02.jpg">
<div>
Description 02
</div>
</li>
</ul>
</div>
</div>
HTML

Let's display 2 cards on PC, but reduce them to 1 on mobile devices.

document.addEventListener( 'DOMContentLoaded', function () {
new Splide( '#card-slider', {
perPage : 2,
breakpoints: {
640: {
perPage: 1,
},
},
} ).mount();
} );
JavaScript

Now we get like the following card slider.

  • Sample Slide 01
    Lorem ipsum dolor sit amet, ad laudem maluisset molestiae ius. Movet nostro in duo, audire vulputate mel cu
  • Sample Slide 02
    Nostrum mentitum ea sit. Ad est alia utroque verterem, ad pri soluta diceret expetenda
  • Sample Slide 03
    Quo harum altera incorrupte ea, eos viris constituto ex
  • Sample Slide 04
    Commodo denique honestatis duo et, an eum noluisse vituperatoribus, ad lorem nonumy tempor ius
  • Sample Slide 05
    Lorem ipsum dolor sit amet, ad laudem maluisset molestiae ius. Movet nostro in duo, audire vulputate mel cu
  • Sample Slide 06
    Nostrum mentitum ea sit. Ad est alia utroque verterem, ad pri soluta diceret expetenda

Note that if you'd like to use the cover option for the card slider, you have to use a container element. See this document for more details.

Fullscreen Slider

As width and height options accept CSS relative units, it’s a piece of cake to create a full screen slider. Simply apply '100vw' and '100vh'.

document.addEventListener( 'DOMContentLoaded', function () {
new Splide( '#fullscreen-slider', {
width : '100vw',
height: '100vh',
} ).mount();
} );
JavaScript