Changing Options

Splide takes various options to customize how the carousel 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 carousels, you may want to set common options shared by all carousels. 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

type: string = 'slide'

The type of the carousel. To loop the fade carousel, enable the rewind option.

'slide'

A carousel with the slide transition

'loop'

A carousel carousel

'fade'

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


role

role: string = 'region'

Sets a role attribute to the root element. It must be a landmark role or group. To prevent Splide from assigning the default value (region), pass an empty string or undefined.

If your root element is <section>, Splide will ignore this option, because <section> with an accessible name has an implicit aria role (make sure to set aria-label or aria-labelledby).

See this document for more information.

If you are using tags that have or may have a landmark role — such as <header> and <nav> — inserting role="region" can be incorrect. For example, <header> has 'banner'


label

label: string

Sets an aria-label attribute to the root element. This option overwrites the attribute defined by HTML.

The label may be inappropriate after destruction, especially if it contains "carousel" or "slider". You can change it by breakpoints:

{
label: 'My Carousel', // Can be omitted if the label is defined in HTML
breakpoints: {
640: {
destroy: true,
label : 'My Gallery', // Used after destruction
}
}
}
JavaScript

Note that if there is a visible heading that is proper for an accessible name of the carousel, reference it by aria-labelledby instead of aria-label.

W3C suggests that the label should not include the word "carousel" because aria-roledescription is set to carousel. Some screen readers announce "label" + "description", but this behaviour is not mandatory according to the spec. Actually, some other screen readers ignore the description. IMO, we can include the word "carousel". They may say "carousel" twice — but it's trivial issue and better than nothing.


labelledby

labelledby: string

Sets an aria-labelledby attribute to the root element. This option overwrites the attribute defined by HTML.


rewind

rewind: boolean = false

Determines whether to rewind the carousel 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 carousel 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

rewindByDrag

rewindByDrag: boolean

Allows users to rewind a carousel by drag. The rewind option must be true.

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

width

width: number | string

Defines the carousel max width, accepting the CSS format such as 10em, 80vw. The example below sets the carousel 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 carousel 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 carousel will ignore perPage, height and heightRatio options if you provide this value.


heightRatio

heightRatio: number

Determines height of slides by the ratio to the carousel width. For example, when the carousel width is 1000 and the ratio is 0.3, the height will be 300. Be aware that 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. Do not provide perPage and perMove options (or set them to 1). Visit this page for more info.

If you are using this and the lazyLoad option together, make sure each slide has explicit width.


autoHeight

autoHeight: boolean = false

If true, the height of slides are determined by their height. Do not provide perPage and perMove options (or set them to 1). Visit this page for more info.

If you are using this and the lazyLoad option together, make sure each slide has explicit height.


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 carousel.

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


cloneStatus

cloneStatus: boolean = true

Determines whether to add is-active class to clones or not.


focus

focus: number | 'center'

Determines which slide should be active if the carousel 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

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

Sets padding left/right for the horizontal carousel or top/bottom for the vertical carousel. 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 (px)
padding: 10
// By the CSS format
padding: '1rem'
// Specifies each value for a horizontal carousel
padding: { left: 10, right: 20 }
padding: { left: '1rem', right: '2rem' }
// Specifies each value for a vertical carousel
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 = true

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


pagination

pagination: boolean = true

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

This option must be false if you are using isNavigation. Otherwise roles and ARIA attributes will be messed up.


paginationKeyboard

paginationKeyboard: boolean = true

Determines whether to enable keyboard shortcuts for pagination when it contains focus. This is required for W3C Carousel Design Pattern.


paginationDirection

paginationDirection: 'ltr' | 'rtl' | 'ttb'

Explicitly sets the pagination direction that does not only affect appearance but also shortcuts and ARIA attributes. The default value is determined by the carousel direction.

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

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 = t => 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 carousel or not.

true

Enables drag

false

Disables drag

'free'

Enables the drag free mode

Here is the example for 'free'.

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

snap

snap: boolean = false

Snaps the closest slide in the drag free mode.

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

noDrag

noDrag: string

The selector for nodes that cannot be dragged.

{
noDrag: 'input, textarea, .no-drag',
}
JavaScript

dragMinThreshold

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

The required distance to start moving the carousel 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 carousel 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 carousel runs. Around 500 is recommended.


flickMaxPages

flickMaxPages: number = 1

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


waitForTransition

waitForTransition: boolean = false

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


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 'pause', it will not begin when the carousel becomes active, which means you need to provide a play button or manually start it by Autoplay#play().

With the Intersection extension, you can enable autoplay only when the carousel is in the viewport.


interval

interval: number = 5000

The autoplay interval duration in milliseconds. Use the data-splide-interval attribute to override this value for the specific slide.

<li class="splide__slide" data-splide-interval="1000"></li>
<li class="splide__slide" data-splide-interval="10000"></li>
HTML

pauseOnHover

pauseOnHover: boolean = true

Determines whether to pause autoplay on mouseover. This should be true for accessibility.


pauseOnFocus

pauseOnFocus: boolean = true

Determines whether to pause autoplay while the carousel 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 | 'global' | 'focused' = false

Enables custom keyboard shortcuts described in the following table:

KeyDescription
Go to the previous page in LTR or the next page in RTL
Go to the next page in LTR or the previous page in RTL
Go to the previous page in TTB
Go to the previous page in TTB

Old Splide inserted tabindex="0" to the root element for the 'focused' value in case that the carousel has no focusable elements, but this version doesn't because:

  • Setting tabindex="0" on a non-interactive content should be avoided
  • A carousel must have a region or group role according to the W3C guideline, but they are not interactive

Note that when pagination contains focus, keybindings for pagination will take precedence if you enable both keyboard and paginationKeyboard.

true

Enables shortcuts only when a carousel contains focus

false

Disables shortcuts

'global'

Enables shortcuts globally, listening to the window keydown event (discouraged)

'focused'

Same with true


wheel

wheel: boolean = false

Enables navigation by the mouse wheel. To use this option, set waitForTransition to be true and/or give wheelSleep duration, otherwise your carousel will immediately reach the end.


wheelMinThreshold

wheelMinThreshold: number

The threshold to cut off the small delta produced by inertia scroll.


wheelSleep

wheelSleep: number

The sleep duration in milliseconds until accepting next wheel. The timer starts when the transition begins.


releaseWheel

releaseWheel: boolean = false

Determines whether to release the wheel event when the carousel reaches the first or last slide so that the user can scroll the page continuously.

  • 01
  • 02
  • 03

direction

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

The direction of the carousel.

'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

Determines whether to add tabindex="0" to visible slides or not. The default value is false when isNavigation is false, and true when isNavigation is true. This is because:


focusableNodes

focusableNodes: string = 'a, button, textarea, input, select, iframe'

The selector to find focusable elements inside slides. When a slide gets hidden (has aria-hidden="true"), Splide assigns tabindex="-1" to its descendant focusable elements for accessibility. See this section for more details.


isNavigation

isNavigation: boolean = false

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

Disable pagination if you enable this option. Otherwise roles and ARIA attributes will be messed up.


trimSpace

trimSpace: boolean | 'move' = true

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

true

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

false

Disables trimming edge spaces

'move'

Trims spaces and always moves the carousel when requested

By default, Splide removes edge spaces. The carousel 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 carousel to stay on the same position, set the option to 'move':

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

omitEnd

omitEnd: boolean = false

Available from version 4.1.0.

If true, omits some pagination dots which just changes the active slide and do not move a carousel. Also, disables a next arrow when a carousel reaches the last page.

To use this option,

  • The type must be slide (or undefined)
  • The focus option must be specified

For example, the following carousel contains 9 slides, but pagination dots are omitted to 7:

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

This option is also useful for fixedWidth and autoWidth:

  • 180
  • 250
  • 200
  • 225
  • 150

updateOnMove

updateOnMove: boolean = false

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

  • 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 carousel.

true

Destroys the carousel but keep observing breakpoints for remount

'completely'

Completely destroys the carousel


mediaQuery

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

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


live

live: boolean = true

Enables a live region. If isNavigation is enabled, Splide won't activate it.


breakpoints

breakpoints: Record<string | number, ResponsiveOptions>

A collection of responsive options for specific breakpoints. By default, Splide uses max-width(desktop-first) to check the device width, but you are able to change it to min-width (mobile-first) by mediaQuery.

This example reduces the number of slides under 640px:

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

If you want to have a carousel only for desktop or mobile, the destroy option is useful:

// A carousel for desktop:
{
breakpoints: {
640: {
destroy: true,
},
}
}
// A carousel for mobile:
{
mediaQuery: 'min',
breakpoints: {
640: {
destroy: true,
},
}
}
JavaScript

reducedMotion

reducedMotion: Options

Options used when the (prefers-reduced-motion: reduce) is detected, which is described in this page. The default value is:

{
speed : 0,
rewindSpeed: 0,
autoplay : 'pause',
}
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.