There are various options to customize how your slider works. They can be changed by a data attribute as well as JavaScript.

Changing Options

By JavaScript

To change default options, pass an object to the second argument of the Splide constructor:

new Splide( '#splide', {
	type   : 'loop',
	perPage: 3,
} );

By Data Attribute

You can also pass options in a JSON format to data-splide attribute of a root element:

<div class="splide" data-splide="{"type":"loop","perPage":3}">
</div>

Note that options defined with a data attribute override the ones with JavaScript(data attribute > JavaScript).

Reference

  • type: Determine a slider type.
  • rewind: Whether to rewind a slider before the first slide or after the last one.
  • speed: Transition speed in milliseconds.
  • rewindSpeed: Transition speed on rewind in milliseconds.
  • width: Define slider max width.
  • height: Define slider height.
  • fixedWidth: Fix width of slides.
  • fixedHeight: Fix height of slides.
  • heightRatio: Determine height of slides by ratio to a slider width.
  • autoWidth: If true, slide width will be determined by the element width itself.
  • perPage: Determine how many slides should be displayed per page.
  • perMove: Determine how many slides should be moved when a slider goes to next or previous page.
  • start: Start index.
  • focus: Determine which slide should be focused.
  • gap: Gap between slides.
  • padding: Set padding-left/right in horizontal mode or padding-top/bottom in vertical one.
  • easing: Animation timing function for CSS transition.
  • arrows: Whether to append arrows.
  • arrowPath: Change the arrow SVG path.
  • pagination: Whether to append pagination(indicator dots).
  • autoplay: Whether to enable autoplay.
  • interval: Autoplay interval in milliseconds.
  • pauseOnHover: Whether to stop autoplay while a slider is hovered.
  • pauseOnFocus: Whether to stop autoplay while a slider elements are focused.
  • lazyLoad: Enable lazy load for images.
  • preloadPages: Determine how many pages around an active slide should be loaded beforehand. This only works the lazyLoad option is “nearby”.
  • keyboard: Whether to control a slider via keyboard.
  • drag: Whether to allow mouse drag and touch swipe.
  • flickThreshold: Threshold for determining if the action is “flick” or “swipe”.
  • flickPower: Determine power of flick. The larger number this is, the farther a slider runs by flick.
  • flickMaxPages: Limit a number of pages to move by flick.
  • direction: Slider direction.
  • cover: Whether to convert an img src to background-image of its parent element. height, fixedHeight or heightRatio is required.
  • accessibility: Whether to enable accessibility(aria and screen reader texts) or not.
  • isNavigation: Determine if a slider is navigation for another.
  • trimSpace: Whether to trim spaces before the fist slide or after the last one.
  • updateOnMove: If true, update slide status(eg. “is-active” class) before transition.
  • breakpoints: Breakpoints definitions.
  • classes: Collection of class names.
  • i18n: Collection of texts for i18n.

type

Determine a slider type, accepting:

  • slide: Regular slider behavior.
  • loop: Carousel slider.
  • fade: Change slides with fade transition. Drag will be disabled in this mode. perPage must be 1 and gap/padding must be 0.

type: string default: 'slide'


rewind

Whether to rewind a slider before the first slide or after the last one. This option is ignored in “loop” mode.

type: boolean default: false

01
02
03
04
05
06
07
08
09
new Splide( '#splide', {
	rewind: true,
} );

speed

Transition speed in milliseconds.

type: number default: 400


rewindSpeed

Transition speed on rewind in milliseconds. The value of the speed option above will be used alternatively when this value is provided.

type: number default: 0


width

Define slider max width. Any CSS relative units are accepted.

type: number|string default: 0

The slider width is 80%.
01
02
03
04
05
06
07
08
09
new Splide( '#splide', {
	width: '80%';
} );

height

Define slider height. Any CSS relative units without % are accepted.

type: number default: 0

The slider height is 20vh.
01
02
03
04
05
06
07
08
09

fixedWidth

Fix width of slides. Any CSS relative units are accepted.

type: number|string default: 0

The width of slides keeps 12rem against any window size.
01
02
03
04
05
06
07
08
09
new Splide( '#splide', {
	fixedWidth: '12rem',
} );

fixedHeight

Fix height of slides. Any CSS relative units without % are accepted.

type: number|string default: 0

The height of slides keeps 8rem against any window size.
01
02
03
04
05
06
07
08
09
new Splide( '#splide', {
	fixedHeight: '8rem',
} );

heightRatio

Determine height of slides by ratio to slider width. This is useful if you want to keep aspect ratio of a slider.

This options doesn’t work when height or fixedHeight is provided.

type: number default: 0

The height keeps 30% of the slider width, responding window size.
01
02
03
04
05
06
07
08
09
new Splide( '#splide', {
	heightRatio: 0.3,
} );

autoWidth

If true, slide width will be determined by the element width itself. See this document for more details.

type: boolean default: false


perPage

Determine how many slides should be displayed per page.

type: number default: 0


perMove

Determine how many slides should be moved when a slider goes to next or previous page.

To display all indicator dots, set focus to 0.

type: number default: 0

3 Slides per page but move slides one by one.
01
02
03
04
05
06
07
08
09
new Splide( '#splide', {
	perPage: 3,
	perMove: 1,
} );

start

Start index.

type: number default: 0

The start index is 2
01
02
03
04
05
06
07
08
09
new Splide( '#splide', {
	start: 2,
} );

focus

Determine which slide should be focused if there are multiple slides in a page. 'center' is acceptable for centering an active slide.

type: boolean|number|string default: 0

Focus is 'center'(trimSpace is disabled).
01
02
03
04
05
06
07
08
09
new Splide( '#splide', {
	focus    : 'center',
	perPage  : 2,
	trimSpace: false,
} );

If you are not comfortable with empty spaces before the first slide and after the last one, enable trimSpace option(it is true as default).

Focus is 'center' and edge spaces are trimmed.
01
02
03
04
05
06
07
08
09
new Splide( '#splide', {
	focus  : 2,
	perPage: 2,
} );

gap

Gap between slides. CSS format is allowed such as 1em.

type: number|string default: 0


padding

Set padding-left/right in horizontal mode or padding-top/bottom in vertical one. Give a single value to set a same size for both sides or do an object for different sizes. Also, CSS format is allowed such as 1em.

var options = {
	// Padding left/right(top/bottom) will be 10px
	padding: 10,
	
	// Padding left/right(top/bottom) will be 1em.
	padding: '1em',
	
	// Define them separately in the ltr or rtl mode.
	padding: {
		left : 0,
		right: '2rem',
	},
	
	// Define them separately in the ttb(vertical) mode.
	padding: {
		top   : '1rem',
		bottom: '3rem',
	}
}

type: object default: false

Padding left is 0 and right is 6rem.
01
02
03
04
05
06
07
08
09
new Splide( '#splide', {
	padding: {
		left : 0,
		right: '6rem',
	}
} );

easing

An animation timing function for CSS transition. For example, 'linear', 'ease' or 'cubic-bezier()'.

type: string default: 'cubic-bezier(.42,.65,.27,.99)'


arrows

If true, arrows will be appended to the root element. If 'slider', they will be done to the slider element(HTML must have a slider div wrapping a track element).

type: boolean|string default: true


arrowPath

The arrow SVG path like 'm7.61 0.807-2.12…'. SVG size must be 40×40.

type: string default: ''


pagination

If true, pagination(indicator dots) will be appended to the root element. If 'slider', it will be done to the slider element(HTML must have a slider div).

type: boolean|string default: true


autoplay

Whether to enable autoplay.

type: boolean default: false


interval

Autoplay interval in milliseconds.

type: number default: 5000


pauseOnHover

Whether to pause autoplay when a slider is hovered.

type: boolean default: true


pauseOnFocus

Whether to pause autoplay when elements inside a slider are focused. true is recommended for accessibility.

type: boolean default: true


lazyLoad

Enable lazy loading.

  • false: Disable lazy loading.
  • 'nearby': Only images around an active slide will be loaded(see preloadPages).
  • 'sequential': All images will be sequentially loaded.

To make lazy load work, img element must have a data-splide-lazy attribute whose value is a path or url to an image file and must not containsrc to prevent a source is automatically loaded.

<li class="splide__slide">
	<img data-splide-lazy="path-to-the-image" alt="cat">
</li>

type: boolean|string default: false


preloadPages

This option works only when a lazyLoad option is "nearby". Determine how many pages(not slides) around an active slide should be loaded beforehand.

type: number default: 1


keyboard

Whether to enable control via keyboard.

Arrow LeftGo to previous page in LTR mode or next page in RTL mode
Arrow RightGo to next page in LTR mode or previous page in RTL mode
Arrow UpGo to previous page in TTB mode.
Arrow DownGo to next page in TTB mode.

type: boolean default: true

A slider has to be active to be navigated by keyboard.


drag

Whether to allow mouse drag and touch swipe.

type: boolean default: true


flickThreshold

Threshold for determining if a drag action is “flick” or “swipe”. Around 0.5 is recommended.

FlickA destination slide will be determined flick speed, considering flickPower and fickMaxPages options.
SwipeA destination slide will be the closest one from a current track position, considering swipe direction.

type: number default: 0.6


flickPower

Determine power of flick. The larger number this is, the farther a slider runs. Around 500 is recommended.

type: number default: 600


flickMaxPages

Limit number of pages to be moved by flick.

type: number default: 1


direction

Determine slider direction. Available values are:

  • 'ltr': Left to right.
  • 'rtl': Right to left.
  • 'ttb': Top to bottom. height or heightRatio option is required.

type: string default: 'ltr'

01
02
03
04
05
06
07
08
09
new Splide( '#splide', {
	direction  : 'ttb',
	heightRatio: 0.6,
	perPage    : 2,
} );

cover

Set img src to background-image of its parent element. Images with various sizes can be displayed as same dimension without troublesome cropping work. height, fixedHeight or heightRatio is required.

type: boolean default: true

new Splide( '#splide', {
	cover  : true,
	height : '8rem',
	perPage: 3,
} );

accessibility

Whether to enable accessibility(ARIA attributes) or not. See this document for more information.

type: boolean default: true


isNavigation

Determine if a slider is a navigation for another. Use sync() API to synchronize two sliders.

type: boolean default: false


trimSpace

Whether to trim spaces before the fist slide or after the last one. See focus or this document.

  • 150
  • 250
  • 200
  • 225
  • 175
  • 150
  • 225
  • 200
  • 150
  • false: Allow spaces.
  • true: Default. Remove spaces but sometimes the slider doesn’t move even when the active index is updated.
  • 'move': Remove spaces and the slider always move when the active index is updated. This mode is not compatible with pagination(indicator dots).

type: boolean|string default: true


updateOnMove

Slide status is updated after transition is completed(the “moved” event) in default. If true, the status will be updated before move.

type: boolean default: false

breakpoints

A collection of options applied on each breakpoint of window width. Acceptable options are:

  • rewind
  • speed
  • width
  • height
  • fixedWidth
  • fixedHeight
  • heightRatio
  • perPage
  • perMove
  • focus
  • gap
  • padding
  • pagination
  • easing
  • destroy

For example, to reduce number of slides under 640px:

var options = {
	perPage: 4,
	breakpoints: {
		640: {
			perPage: 2,
		},
	}
};

If destroy option is available, the slider will be destroyed. This option accepts 2 values:

  • true: Destroy Splide but keep monitoring window width to remount it for other breakpoints.
  • 'completely': Destroy Splide completely.
var options = {
	perPage: 3,
	breakpoints: {
		640: {
			destroy: true, // or 'completely'
		},
	}
};

type: boolean|Object default: false


classes

Collection of class names.

type: Object


i18n

Collection of texts for i18n.

type: Object

User's Guide
Tutorials
Extensions