Changing Options

Splide takes various options to customize how the slider works. You can change them in 3 ways.

By JavaScript

The Splide constructor accepts options as the second argument:

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

By Data Attribute

You can also pass options in the JSON format through the data-splide attribute:

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

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

Note that options of the data attribute override the ones provided by the constructor.

By Static Property (Advanced)

If you have multiple sliders, you may want to set common options shared by all sliders. You can set default options by the Splide.defaults static property:

Splide.defaults = {
type : 'loop',
perPage: 2,
}
JavaScript

Splide uses these options as default and overwrites them by options from the constructor and the data attribute.

Options

Splide has 2 different kinds of options - readonly options and responsive options.

You can update responsive options by breakpoints or by passing an object to Splide#options, whereas you must not update readonly options. They'll seem to respond to dynamic change, but Splide does not guarantee the behavior.

Here is the list of all options. Responsive options have the mark.

type

The type of the slider

rewind

Determines whether to rewind the slider or not

speed

The transition speed in milliseconds

rewindSpeed

The transition speed on rewind in milliseconds

width

Defines the slider max width, accepting the CSS format such as 10em, 80vw

height

Defines the slider height, accepting the CSS format except for %

fixedWidth

Fixes width of slides, accepting the CSS format

fixedHeight

Fixes height of slides, accepting the CSS format except for %

heightRatio

Determines height of slides by the ratio to the slider width

autoWidth

If true, the width of slides are determined by their width

autoHeight

If true, the height of slides are determined by their height

start

The start index

perPage

Determines the number of slides to display in a page

perMove

Determines the number of slides to move at once

clones

Explicitly determines the number of clones on each side of the slider

focus

Determines which slide should be active if there are multiple slides in a page

gap

The gap between slides. The CSS format is acceptable

padding

Sets padding left/right or top/bottom of the slider. The CSS format is acceptable

arrows

Determines whether to create/find arrows or not

pagination

Determines whether to create pagination (indicator dots) or not

easing

The timing function for the CSS transition

easingFunc

The easing function for the drag free mode

drag

Determines whether to allow to drag the slider or not

dragMinThreshold

The required distance to start moving the slider by the touch action

flickPower

Determine the power of "flick". The larger number this is, the farther the slider runs

flickMaxPages

Limits the number of pages to move by the flick action

waitForTransition

Determines whether to disable any actions while the slider is transitioning

arrowPath

Changes the arrow SVG path, like 'm7.61 0.807-2.12...'

autoplay

Determines whether to activate autoplay or not

interval

The autoplay interval in milliseconds

pauseOnHover

Determines whether to pause autoplay on mouseover

pauseOnFocus

Determines whether to pause autoplay when the slider contains a focused element

resetProgress

Determines whether to reset the autoplay progress when it is requested to start again

lazyLoad

Enables lazy loading

preloadPages

Determine how many pages (not slides) around the active slide should be loaded beforehand

keyboard

Determines whether to enable keyboard shortcuts or not

wheel

Enables navigation by the mouse wheel

direction

The direction of the slider

cover

Converts the image src to the css background-image URL of the parent element

slideFocus

Determines whether to add tabindex="0" to visible slides or not

isNavigation

If true, the slider makes slides clickable to navigate another slider

trimSpace

Determines whether to trim spaces before/after the slider if the focus option is available

updateOnMove

Updates the is-active status of slides just before moving the slider

mediaQuery

If min, the media query for breakpoints will be min-width, or otherwise, max-width

breakpoints

The collection of responsive options for specific breakpoints

classes

The collection of class names

i18n

The collection of i18n strings

destroy

Destroys the slider


type

type: string = 'slide'

The type of the slider.

'slide'

A slider with the slide transition

'loop'

A carousel slider

'fade'

A slider with the fade transition. This does not support the perPage option


rewind

rewind: boolean = false

Determines whether to rewind the slider or not. This does not work in the loop mode.

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

speed

speed: number = 400

The transition speed in milliseconds. If 0, the slider immediately jumps to the target slide.


rewindSpeed

rewindSpeed: number

The transition speed on rewind in milliseconds. The speed value is used as default.

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

width

width: number | string

Defines the slider max width, accepting the CSS format such as 10em, 80vw. The example below sets the slider width to 80%.

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

height

height: number | string

Defines the slide height, accepting the CSS format except for %.


fixedWidth

fixedWidth: number | string

Fixes width of slides, accepting the CSS format. The slider will ignore the perPage option if you provide this value.

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

fixedHeight

fixedHeight: number | string

Fixes height of slides, accepting the CSS format except for %. The slider will ignore perPage, height and heightRatio options if you provide this value.


heightRatio

heightRatio: number

Determines height of slides by the ratio to the slider width. For example, when the slider width is 1000 and the ratio is 0.3, the height will be 300.

Splide ignores this option when height or fixedHeight is provided.
  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

autoWidth

autoWidth: boolean = false

If true, the width of slides are determined by their width. The perPage and perMove options should be 1.


autoHeight

autoHeight: boolean = false

If true, the height of slides are determined by their height. The perPage and perMove options should be 1.


start

start: number = 0

Defines the start index.

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

perPage

perPage: number = 1

Determines the number of slides to display in a page. The value must be an integer.


perMove

perMove: number

Determines the number of slides to move at once. The following example displays 3 slides per page but moves slides one by one. The value must be an integer.

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

clones

clones: number

Specifies the number of clones on each side of the loop slider.

Do not set this value if you unsure how this option affects the slider.

focus

focus: number | 'center'

Determines which slide should be active if the slider has multiple slides in a page. By default, Splide trims edge spaces like this:

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

If you want to show these spaces, disable the feature by the trimSpace option.

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

gap

gap: number | string

The gap between slides. The CSS format is acceptable, such as 1em.


padding

gap: number | string | { left?: number | string, right?: number | string } | { top?: number | string, bottom?: number | string }

Sets padding left/right for the horizontal slider or top/bottom for the vertical slider. Provide a single value to set the same size for both, or an object literal for different sizes. The CSS format is acceptable, such as 1em.

// By number
padding: 10
// By the CSS format
padding: '1rem'
// Specifies each value for a horizontal slider
padding: { left: 10, right: 20 }
padding: { left: '1rem', right: '2rem' }
// Specified each value for a vertical slider
padding: { top: 10, bottom: 20 }
JavaScript

The example below has the 20% padding on each side:

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

arrows

arrows: boolean | 'slider' = true

Determines whether to create arrows or not. This option still must be true if you provide arrows by HTML.

true

Appends arrows to the root element

false

Disables arrows

'slider'

Appends arrows to the slider element


pagination

pagination: boolean | 'slider' = true

Determines whether to create pagination (indicator dots) or not.

true

Appends pagination to the root element

false

Disables pagination

'slider'

Appends pagination to the slider element


easing

easing: string = cubic-bezier(0.25, 1, 0.5, 1)

The timing function for the CSS transition, such as linear, ease or cubic-bezier().


easingFunc

easingFunc: ( t: number ) => number = 1 - Math.pow( 1 - t, 4 )

The easing function for the drag free mode.


drag

drag: boolean | 'free' = true

Determines whether to allow the user to drag the slider or not.

true

Enables drag

false

Disables drag

'free'

Enables the drag free mode

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

dragMinThreshold

dragMinThreshold: number | { mouse: number, touch: number } = 10

The required distance to start moving the slider by the touch action. If you also want to set the threshold for a mouse, provide an object.

These 2 settings lead the same result:

{
dragMinThreshold: 10,
}
{
dragMinThreshold: {
mouse: 0,
touch: 10,
},
}
JavaScript
The value is important to evaluate whether the user wants to vertically scroll the page or drag the slider horizontally. The touch threshold does not accept 0.

flickPower

flickPower: number = 600

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


flickMaxPages

flickMaxPages: number = 1

Limits the number of pages to move by the flick action.


waitForTransition

waitForTransition: boolean = true

Determines whether to disable any actions while the slider is transitioning. Even if false, the slider forcibly waits for the transition on the loop points.

This should be true if you are using the wheel option.


arrowPath

arrowPath: string

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


autoplay

autoplay: boolean | 'pause' = false

Determines whether to enable autoplay or not. If 'paused', it will not begin when the slider becomes active, which means you need to provide a play button or manually start it by Autoplay#play().


interval

interval: number = 5000

The autoplay interval duration in milliseconds.


pauseOnHover

pauseOnHover: boolean = true

Determines whether to pause autoplay on mouseover.


pauseOnFocus

pauseOnFocus: boolean = true

Determines whether to pause autoplay while the slider contains the active element (focused element). This should be true for accessibility.


resetProgress

resetProgress: boolean = true

Determines whether to reset the autoplay progress when it is requested to start again.


lazyLoad

lazyLoad: boolean | 'nearby' | 'sequential' = false

Enables lazy loading.

false

Disables lazy loading

'nearby'

Starts loading only images around the active slide (page)

'sequential'

Loads images sequentially

To make lazy load work, the img element in the slide must have the data-splide-lazy attribute that indicates the path or URL to the source file:

<li class="splide__slide">
<img data-splide-lazy="path-to-the-image" alt="cat">
</li>
<!-- or -->
<li class="splide__slide">
<img
src="data:image/png;base64,..."
data-splide-lazy="path-to-the-image"
alt="cat"
>
</li>
HTML

Or use data-splide-lazy-srcset for the srcset:

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

preloadPages

preloadPages: number = 1

Determines how many pages (not slides) around the active slide should be loaded beforehand. This only works when the lazyLoad option is 'nearby'.

This is not strictly tied to the page index, but used just for calculating the index range to load images by perPage * ( preloadPages + 1 ) - 1. For example, if the perPage is 2 and the current index is 0, the result will be 3 and the range will become [ -3, 3 ] (the negative range is used for clones).

keyboard

keyboard: boolean | 'focused' = true

Determines whether to enable keyboard shortcuts or not. If enabled, you can control the slider by arrow keys. This must be enabled for accessibility.

true

Listens to the keydown event of the document

false

Disables keyboard shortcuts

'focused'

Listens to the keydown event of the slider root element with adding tabindex="0" to it


wheel

keyboard: boolean = false

Enables navigation by the mouse wheel. The waitForTransition option should be true.


direction

direction: 'ltr' | 'rtl' | 'ttb' = 'ltr'

The direction of the slider.

'ltr'

Left to right

'rtl'

Right to left

'ttb'

Top to bottom


cover

cover: boolean = false

Converts the image src to the css background-image URL of the parent element. This requires height, fixedHeight or heightRatio option.

This option does not support the srcset.


slideFocus

slideFocus: boolean = true

Determines whether to add tabindex="0" to visible slides or not.


isNavigation

isNavigation: boolean = false

If true, the slider makes slides clickable to navigate another slider. Use Splide#sync() to sync multiple sliders.


trimSpace

trimSpace: boolean | 'move' = true

Determines whether to trim spaces before/after the slider if the focus option is available.

true

Trims spaces. The slider may stay on the same location even when requested to move

false

Disables trimming edge spaces

'move'

Trims spaces and always moves the slider when requested

By default, Splide removes edge spaces. The slider sometimes does not move with changing the active slide:

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

You can display spaces by setting the option to false:

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

If you want to remove spaces, but do not want the slider to stay on the same position, set the option to 'move':

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

updateOnMove

updateOnMove: boolean = false

Updates the is-active status class just before moving the slider.

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

destroy

destroy: boolean | 'completely' = false

Destroys the slider.

true

Destroys the slider but keep observing breakpoints for remount

'completely'

Completely destroys the slider


mediaQuery

mediaQuery: 'min' | 'max' = 'max'

If min, the media query for breakpoints will be min-width, or otherwise max-width.


breakpoints

breakpoints: Record<string | number, ResponsiveOptions>

A collection of responsive options for specific breakpoints.

This example reduces the number of slides under 640px:

{
perPage: 4,
breakpoints: {
640: {
perPage: 2,
},
}
}
JavaScript

You can destroy the slider at the specific breakpoint like this:

{
breakpoints: {
640: {
destroy: true,
},
}
}
JavaScript

classes

classes: Record<string, string>

The collection of class names. To add your own classes to arrows or pagination buttons, provide them with original classes:

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();
JavaScript

Do not remove default classes because Splide refers them for styling.


i18n

i18n: Record<string, string>

The collection of i18n strings. See this document for more details.