Extension

You're browsing the documentation for v3

Extension

Splide is built with several components that add the specific feature to the slider. It accepts additional components as extensions to enhance the slider capability.

Creating A Component

A Component is a function that returns an object with public properties and methods. Here is a bone example of a component constructor:

export function MyExtension( Splide, Components, options ) {
/**
* Optional. Called when the component is mounted.
*/
function mount() {
console.log( 'Hello, Splide!' );
}
/**
* Optional. Called when the Splide destroys the slider.
*/
function destroy() {
console.log( 'Bye!' );
}
return {
mount,
destroy,
};
}
JavaScript

The constructor takes 3 arguments:

SplideSplide

The Splide instance.

ComponentsComponents

The collection of all components.

optionsOptions

The latest options.

You can access all public properties and methods of the Splide class and core components.

export function MyExtension( Splide, Components, options ) {
function mount() {
// Outputs the current index
console.log( Splide.index );
// Outputs all Slide sub components
console.log( Components.Slides.get() );
}
return {
mount,
}
}
JavaScript

Registration

To register created extensions, pass an object with them to the Splide#mount() method:

import Splide from '@splidejs/splide';
import { MyExtension01 } from '...';
import { MyExtension02 } from '...';
new Splide( '#splide' ).mount( {
MyExtention01,
MyExtension02,
} );
JavaScript

Be aware that the component name must be unique. Do not use names of core components.

Listening to Events

The easiest way to attach a handler to an event is using Splide#on().

export function MyExtension( Splide, Components, options ) {
function mount() {
Splide.on( 'resize', onResize );
}
function onResize() {
// do something
}
return {
mount,
};
}
JavaScript

Another way is using the EventInterface() constructor. This encapsulates handlers by the unique key, and protects them from unexpected removal. It also provides the interface to listen to native events.

import { EventInterface } from '@splidejs/splide';
export function MyExtension( Splide, Components, options ) {
const { on, off, bind, unbind } = EventInterface( Splide );
function mount() {
// Listens to an internal event
on( 'resize', () => {} );
// Removes the listener
off( 'resize' );
// Listens to a native event
bind( window, 'resize', () => {} );
// Listens to a native event
unbind( window, 'resize' );
}
...
}
JavaScript

Note that all registered handlers will be removed when the Splide is destroyed by Splide#destroy() or the destroy option.

Example

Let's try to make a simple extension that displays the current slide number and the total number of slides in the ${ slide }/${ total } format.

Creating An Element

First, we need to create an element to display numbers:

export function SlideNumber( Splide, Components ) {
const { track } = Components.Elements;
let elm;
function mount() {
elm = document.createElement( 'div' );
elm.style.textAlign = 'center';
elm.style.marginTop = '0.5em';
// Insert the element after the track
track.parentElement.insertBefore( elm, track.nextSibling );
}
return {
mount,
};
}
JavaScript

The Elements component stores main elements that constitute the slider, such as track, list and slides. In the example above, we insert the created element after the track.

Initializing and Updating Numbers

We can get the current index from Splide#index and the number of slides from Splide#length. Also, we can update the index by listening to the move event fired every time when the slider moves.

export function SlideNumber( Splide, Components ) {
const { track } = Components.Elements;
let elm;
function mount() {
elm = document.createElement( 'div' );
elm.style.textAlign = 'center';
elm.style.marginTop = '0.5em';
track.parentElement.insertBefore( elm, track.nextSibling );
update();
Splide.on( 'move', update );
}
function update() {
elm.textContent = `${ Splide.index + 1 }/${ Splide.length }`;
}
return {
mount,
};
}
JavaScript

That's all! 🎉 The result will be like this:

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09