Options

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>

In this example, the data value is enclosed by single quotes to use double quotes in JSON string, or you need to escape them with &quot;.

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.
  • waitForTransition: Whether to prevent any actions while a slider is transitioning.
  • 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. This is for a horizontal slider.
  • autoHeight: If true, slide height will be determined by the element height itself. This is for a vertical slider.
  • 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.
  • clones: Manually determine how many clones should be generated on one side.
  • 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.
  • resetProgress: Whether to reset progress of the autoplay timer when resumed.
  • 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.
  • dragAngleThreshold: The angle threshold for drag.
  • swipeDistanceThreshold: Distance threshold for determining if the action is “flick” or “swipe”.
  • flickVelocityThreshold: Velocity 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.
  • slideFocus: Whether to add tabindex=”0″ to visible slides or not.
  • isNavigation: Determine if a slider is navigation for another.
  • trimSpace: Whether to trim spaces before the first slide or after the last one.
  • updateOnMove: If true, is-active class added to the slide element before transition.
  • throttle: Throttle duration for the resize event.
  • 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. 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 not provided.

type: number default: 0

waitForTransition

Whether to prevent any actions while a slider is transitioning. If false, navigation, drag and swipe work while the slider is running. But even so, it will be forced to wait in some cases of the loop mode to shift a slider.

type: boolean default: true

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

autoHeight

If true, slide height will be determined by the element height 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,
} );

clones

Manually determine how many clones should be generated on one slide. The total number of clones will be twice of this for both sides. You don’t need to modify this value in most cases.

type: number default: 0

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

resetProgress

Whether to reset progress of the autoplay timer when resumed.

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

Also, data-splide-lazy-srcset is available for a srcset attribute.

<li class="splide__slide">
	<img
    data-splide-lazy-srcset="600.jpg 600w, 1000.jpg 1000w"
    sizes="100vw"
    data-splide-lazy="1000.jpg"
		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.

  • true or 'global': Listen to the keydown event of the document.
  • 'focused': Listen to the keydown event of the slider root element. tabindex="0" will be added to it.
  • false: Disable keyboard shortcuts.

If true or 'global' and there are multiple slides in a page, all slides will correspond with the same keyboard event. The ‘focused’ option can prevent this, but the slider needs to be focused by click or tab key.

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|string default: global

drag

Whether to allow mouse drag and touch swipe.

type: boolean default: true

dragAngleThreshold

The angle threshold for drag. The slider starts moving only when the drag angle is less than this threshold.

type: numberdefault: 30

swipeDistanceThreshold

Distance threshold for determining if the action is “flick” or “swipe”. When a drag distance is over this value, the action will be treated as “swipe”, not “flick”.

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: 150

flickVelocityThreshold

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

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: false

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

slideFocus

Whether to add tabindex="0" to visible slides or not.

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 first 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

The is-active class is added after transition is completed(the “moved” event) by default. If true, it will be added before transition.

This doesn’t perfectly work when a slide and its clone are shown at the same time. For example, when number of slides is less than perPage or using fixedWidth with a few slides, you will see 2(or more) active slides while transitioning.

type: boolean default: false

throttle

Throttle duration in milliseconds for the window resize event.

type: number default: 100

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
  • drag
  • 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. To add your own classes to arrows or pagination buttons, provide them with original classes like this:

new Splide( '#splide', {
	classes: {
		// Add classes for arrows.
		arrows: 'splide__arrows your-class-arrows',
		arrow : 'splide__arrow your-class-arrow',
		prev  : 'splide__arrow--prev your-class-prev',
		next  : 'splide__arrow--next your-class-next',
		
		// Add classes for pagination.
		pagination: 'splide__pagination your-class-pagination', // container
		page      : 'splide__pagination__page your-class-page', // each button
	},
} ).mount();

type: Object

i18n

Collection of texts for i18n. Visit here for more details.

type: Object

User's Guide
Tutorials
Extensions
Integration