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 "
.
Note that options defined with a data attribute override the ones with JavaScript(data attribute > JavaScript).
Reference
type
Determine a slider type, accepting:
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
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
80%
.new Splide( '#splide', {
width: '80%';
} );
height
Define slider height. Any CSS relative units without % are accepted.
type: number
default: 0
20vh
.fixedWidth
Fix width of slides. Any CSS relative units are accepted.
type: number|string
default: 0
12rem
against any window size.new Splide( '#splide', {
fixedWidth: '12rem',
} );
fixedHeight
Fix height of slides. Any CSS relative units without % are accepted.
type: number|string
default: 0
8rem
against any window size. 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
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:
default: boolean
false
autoHeight
If true
, slide height will be determined by the element height itself. See this document for more details.
type:
default: boolean
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
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
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
'center'
(trimSpace
is disabled).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).
'center'
and edge spaces are trimmed.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
6rem
.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.
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.
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 Left | Go to previous page in LTR mode or next page in RTL mode |
---|---|
Arrow Right | Go to next page in LTR mode or previous page in RTL mode |
Arrow Up | Go to previous page in TTB mode. |
Arrow Down | Go 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: number
default: 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”.
Flick | A destination slide will be determined flick speed, considering flickPower and fickMaxPages options. |
---|---|
Swipe | A 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:
type: string
default: 'ltr'
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.
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:
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:
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