APIs – Splide

Splide provides some properties and methods through its instance to control or customize a slider programmatically.

Properties

`root`

type: Element

Root element.

var splide = new Splide( '#splide' ).mount();
splide.root.classList.add( 'awesome-slider' );

`index`

type: number

Active index(zero-based).

var splide = new Splide( '#splide' ).mount();
console.log( splide.index ); // 0
// Go to next slide
splide.go( '+1' ); 
console.log( splide.index ); // 1

`options`

type: Object

The latest options. If you set a new object containing new options, old and new objects will be merged.

var splide = new Splide( '#splide', {
	perPage: 3,
	focus  : 'center',
} );

console.log( splide.options.perPage ); // 3
console.log( splide.options.focus ); // 'center'

// A new object will be merged to current options.
splide.options = { perPage: 1 };

console.log( splide.options.perPage ); // 1
console.log( splide.options.focus ); // 'center'

`length`

type: number

Number of slides without clones.

`classes`

type: Object

A collection of class names. This is an alias of options.classes.

`i18n`

type: Object

A collection of texts for i18n. This is an alias of options.i18n.

`Components`

type: Object

An object containing all components, such as Elements, Layout, Controller etc.

var splide = new Splide( '#splide' ).mount();
// Output a track element
console.log( splide.Components.Elements.track );
// Output all slide elements.
console.log( splide.Components.Elements.slides );

`State`

type: Object

Hold a State object containing 2 methods:

set( state ): Set a new state(Do not use this).
is( state ): Verify if current state is given one or not.

And there are 5 states defined:

STATES.CREATED: Splide instance has just been created.
STATES.MOUNTED: All components have been mounted.
STATES.IDLE: Idling.
STATES.MOVING: The slider is moving.
STATES.DESTROYED: Splide has been destroyed.

var splide = new Splide( '#splide' ).mount();

// Ensure the slider is not moving.
if ( ! splide.State.is( splide.STATES.MOVING ) ) {
	// do something.
}

`Event`

type: Object

An Event object. In most cases, you don’t need to access this property directly. Use on() or emit() methods below.

Methods

`mount( Extensions = {}, Transition = null )`

Mount all components and start initialization. This function must be called to make a slider work.

Parameters

{Object} Extensions: Optional. An object containing extra components.
{function} Transition: Optional. Custom transition component.

Return

{Splide|null} Splide instance or null if an error occurred.

var splide = new Splide( '#splide' );
splide.mount();

`on( event, handler, elm = null, options = {} )`

Listen to internal or native event(s). All events will be

Parameters

{string} event: An event name or names separated by a space. Use a dot to join namespace.
{function} handler: Callback function fired on the event(s).
{Element} elm: Optional. If this value is given, listen to a native event by addEventListener().
{Object} options: Optional. Options for addEventListener().

Return

{Splide} Splide instance to chain methods.

var splide = new Splide( '#splide' ).mount();

splide.on( 'moved', function() {
	// do something
} );

// Listen to multiple events.
splide.on( 'moved updated', function() {
	// do something
} )

// Add namespace.
splide.on( 'moved.namespace', function() {
	// do something.
} );

// Listen to a native event.
var track = splide.Components.Elements.track;
splide.on( 'click', function() {
	// do something.
}, track );

`off( event, elm = null )`

Unbind handlers from the given event(s).

off() removes all handlers including ones used internally. To unbind only your handlers, append a namespace after an event name.

Parameters

{string} event: An event name or names separated by a space. Use a dot to join namespace.
{Element} elm: Optional. If this value is given, the registered listener will be removed from the element by removeEventListener().

Return

{Splide} Splide instance to chain methods.

var splide = new Splide( '#splide' ).mount();

// Listen to the "moved" event
splide.on( 'moved.yourNamespace', function() {
	// do something
} );

// Remove only your handler
splide.off( 'moved.yourNamespace' );

// Remove a listener from a native event.
var track = splide.Components.Elements.track;
splide.off( 'click', track );

`emit( event, ...args )`

Emit an event by name with/without arguments.

Parameters

{string} event: Event name.
{*} ...args: Any number of arguments passed to registered listeners.

Return

{Splide} Splide instance to chain methods.

var splide = new Splide( '#splide' ).mount();

splide.on( 'myEvent', function( drink, index ) {
	console.log( drink ); // 'coffee'
	console.log( index ); // 5
} );

splide.emit( 'myEvent', 'coffee', 5 );

`go( control, wait = true )`

Go to the slide specified by the given control.

Parameters

{string|number} control: Control pattern. See the table below for details.
{boolean} wait: Optional. Whether to wait for transition.

Controls

{number}: Go to slide specified by {number}.
'+','+{number}': Increase active slide index.
'-','-{number}': Decrease active slide index.
'>','>{number}': Go to next page or the page specified by {number}. For example, '>2' moves a slider to page 2.
'<','<{number}': Go to previous page or the page specified by {number}.

If perMove option is provided, '>' and '<' moves the slider according to the number.

var splide = new Splide( '#splide' ).mount();

// Go to first slide.
splide.go( 0 );

// Go to last slide.
splide.go( splide.length - 1 );

// Go to next slide.
splide.go( '+' );

// Go to slide after the next.
splide.go( '+2' );

// Go to next page or next "perMove" slide.
splide.go( '>' );

// Go to page 2.
splide.go( '>2' );

`is( type )`

Verify whether the slider type is the given one or not.

Parameters

{string} type: Slider type.

Types

SLIDE = 'slide'
LOOP = 'loop'
FADE = 'fade'

Return

true if a slider type is the provided one or false if not.

var splide = new Splide( '#splide' ).mount();

if ( splide.is( 'loop' ) ) {
	// Do something.
}

`sync( splide )`

When the active index of the main slider is updated, the one of the registered slider is attempt to be corresponded, and vice versa. The number of slides should be same between two sliders.

Parameters

{Splide} splide: Splide instance.

Return

{Splide} Splide instance to chain methods.

// Create and mount the thumbnails slider.
var thumbnailsSplide = new Splide( '#splide-thumbnails', {
	rewind      : true,
	fixedWidth  : 100,
	fixedHeight : 64,
	isNavigation: true,
	gap         : 10,
	focus       : 'center',
	pagination  : false,
	cover       : true,
	breakpoints : {
		'600': {
			fixedWidth  : 66,
			fixedHeight : 40,
		}
	}
} ).mount();

// Create the main slider.
var primarySplide = new Splide( '#splide-primary', {
	type       : 'fade',
	heightRatio: 0.5,
	pagination : false,
	arrows     : false,
	cover      : true,
} );

// Set the thumbnails slider as a sync target and then call mount.
primarySplide.sync( thumbnailsSplide ).mount();

`add( slide, index = -1 )`

Add a slide to designated position. If index is -1 or invalid, the slide will be added to the end.

Parameters

{string|Element} slide: A slide element or HTML string.
{number} index: Optional. Position where the slide will be inserted.

Return

{Splide} Splide instance to chain methods.

var splide = new Splide( '#splide', {
	perPage: 3,
	rewind : true,
} ).mount();

var addButton    = document.querySelector( '.js-add-button' );
var removeButton = document.querySelector( '.js-remove-button' );

addButton.addEventListener( 'click', function() {
	splide.add( '<li class="splide__slide">' + ( splide.length + 1 ) + '</li>' );
} );

removeButton.addEventListener( 'click', function() {
	splide.remove( splide.length - 1 );
} );

`remove( index )`

Remove a slide. remove( splide.length ) will remove the last slide in a slider.

Parameters

{number} index: Slide index.

Return

{Splide} Splide instance to chain methods.

`refresh()`

Refresh a Splide. Destroy Slide objects and clones, then recreate them. Call “updated” event after that.

Return

{Splide} Splide instance to chain methods.

`destroy( completely = true )`

Destroy Splide. Be aware that all handlers registered by on() will be removed.

Parameters

{boolean} completely: Optional. If false, breakpoints component will keep monitoring window resize event.

Return

{Splide} Splide instance to chain methods.