Options
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
new Splide( '.splide', { type : 'loop', perPage: 3, } );
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
<div class="splide" data-splide='{"type":"loop","perPage":3}'> </div>
In this example, the value is enclosed by single quotes to use double quotes in JSON string,
or you need to escape them with "
.
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.defaults = { type : 'loop', perPage: 2, }
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.
'slide' |
---|
'loop' |
'fade' |
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.
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
{ label: 'My Carousel', // Can be omitted if the label is defined in HTML breakpoints: { 640: { destroy: true, label : 'My Gallery', // Used after destruction } } }
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
.
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.
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.
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.
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
gap: 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
// 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 }
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.
paginationKeyboard
pagination: boolean = true
Determines whether to enable keyboard shortcuts for pagination when it contains focus. This is required for W3C Carousel Design Pattern.
paginationDirection
pagination: '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 |
---|
false |
'free' |
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
{ noDrag: 'input, textarea, .no-drag', }
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
{ dragMinThreshold: 10, } { dragMinThreshold: { mouse: 0, touch: 10, }, }
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 'paused'
, 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()
.
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
<li class="splide__slide" data-splide-interval="1000"></li> <li class="splide__slide" data-splide-interval="10000"></li>
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 |
---|
'nearby' |
'sequential' |
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
<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>
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
<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>
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'
.
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:
Key | Description |
---|---|
← | 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
orgroup
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 |
---|
false |
'global' |
'focused' |
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' |
---|
'rtl' |
'ttb' |
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.
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:
isNavigation
makes slides clickable to control another carousel- Clickable elements must be focusable for keyboard users
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.
trimSpace
trimSpace: boolean | 'move' = true
Determines whether to trim spaces before/after the carousel if the focus
option is available.
true |
---|
false |
'move' |
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
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 |
---|
'completely' |
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.
This example reduces the number of slides under 640px
:
{
perPage
:
4
,
breakpoints
:
{
640
:
{
perPage
:
2
,
}
,
}
}
JavaScript
{ perPage: 4, breakpoints: { 640: { perPage: 2, }, } }
You can destroy the carousel at the specific breakpoint like this:
{
breakpoints
:
{
640
:
{
destroy
:
true
,
}
,
}
}
JavaScript
{ breakpoints: { 640: { destroy: true, }, } }
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
{ speed : 0, rewindSpeed: 0, autoplay : 'pause', }
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
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();
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.