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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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

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,
  };
}

The constructor takes 3 arguments:

`Splide`	`Splide`	The Splide instance.
`Components`	`Components`	The collection of all components.
`options`	`Options`	The latest options.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
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

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,
  }
}

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

import Splide from '@splidejs/splide';
import { MyExtension01 } from '...';
import { MyExtension02 } from '...';


new Splide( '#splide' ).mount( {
  MyExtention01,
  MyExtension02,
} );

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

1
2
3
4
5
6
7
8
9
10
11
12
13
export function MyExtension( Splide, Components, options ) {
  function mount() {
    Splide.on( 'resize', onResize );
  }

  function onResize() {
    // do something
  }

  return {
    mount,
  };
}
JavaScript

export function MyExtension( Splide, Components, options ) {
  function mount() {
    Splide.on( 'resize', onResize );
  }


  function onResize() {
    // do something
  }


  return {
    mount,
  };
}

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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

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' );
  }


  ...
}

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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

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,
  };
}

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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

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,
  };
}

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