Svelte Splide
Introduction
Svelte Splide is a Svelte component for a Splide slider/carousel.
You are reading documentation for v0.2.0 or newer.
- The old document has been archived here
- To upgrade from older versions, check out Migrating from v3
Installation
Get the latest version by NPM:
$ npm install @splidejs/svelte-splide
$ npm install @splidejs/svelte-splide
Usage
Components
Import Splide
and SplideSlide
components:
import
{
Splide
,
SplideSlide
}
from
'@splidejs/svelte-splide'
;
JavaScript
import { Splide, SplideSlide } from '@splidejs/svelte-splide';
and render them like this:
<
Splide
aria-label
=
"My Favorite Images"
>
<
SplideSlide
>
<
img
src
=
"image1.jpg"
alt
=
"Image 1"
/
>
<
/
SplideSlide
>
<
SplideSlide
>
<
img
src
=
"image2.jpg"
alt
=
"Image 2"
/
>
<
/
SplideSlide
>
<
/
Splide
>
Svelte
<Splide aria-label="My Favorite Images"> <SplideSlide> <img src="image1.jpg" alt="Image 1"/> </SplideSlide> <SplideSlide> <img src="image2.jpg" alt="Image 2"/> </SplideSlide> </Splide>
If you have the visible heading for the carousel, use aria-labelledby
instead of aria-label
.
See this page for more details.
CSS
Select a CSS file you want to use, and import it:
// Default theme
import
'@splidejs/svelte-splide/css'
;
// or other themes
import
'@splidejs/svelte-splide/css/skyblue'
;
import
'@splidejs/svelte-splide/css/sea-green'
;
// or only core styles
import
'@splidejs/svelte-splide/css/core'
;
JavaScript
// Default theme import '@splidejs/svelte-splide/css'; // or other themes import '@splidejs/svelte-splide/css/skyblue'; import '@splidejs/svelte-splide/css/sea-green'; // or only core styles import '@splidejs/svelte-splide/css/core';
Custom Structure
Although <Splide>
renders a track element by default,
you can handle them respectively with the hasTrack
prop and the <SplideTrack>
component.
In a nutshell, following 2 components render the same HTML:
<
Splide
>
<
SplideSlide
>
...
<
/
SplideSlide
>
<
/
Splide
>
<
Splide
hasTrack
=
{
false
}
>
<
SplideTrack
>
<
SplideSlide
>
...
<
/
SplideSlide
>
<
/
SplideTrack
>
<
/
Splide
>
Svelte
<Splide> <SplideSlide>...</SplideSlide> </Splide> <Splide hasTrack={ false }> <SplideTrack> <SplideSlide>...</SplideSlide> </SplideTrack> </Splide>
Separating <SplideTrack>
from <Splide>
allows you to place arrows, pagination or other controls anywhere outside the track in the similar way of vanilla Splide. For example, Splide renders arrows before a track by default, but you are able to specify the location with a placeholder:
<
Splide
hasTrack
=
{
false
}
aria-label
=
"..."
>
<
div
class
=
"custom-wrapper"
>
<
SplideTrack
>
<
SplideSlide
>
...
<
/
SplideSlide
>
<
/
SplideTrack
>
<
div
class
=
"splide__arrows"
/
>
<
/
div
>
<
/
Splide
>
Svelte
<Splide hasTrack={ false } aria-label="..."> <div class="custom-wrapper"> <SplideTrack> <SplideSlide>...</SplideSlide> </SplideTrack> <div class="splide__arrows" /> </div> </Splide>
...or with custom arrows:
<
Splide
hasTrack
=
{
false
}
aria-label
=
"..."
>
<
SplideTrack
>
<
SplideSlide
>
...
<
/
SplideSlide
>
<
/
SplideTrack
>
<
div
class
=
"splide__arrows"
>
<
button
class
=
"splide__arrow splide__arrow--prev"
>
Prev
<
/
button
>
<
button
class
=
"splide__arrow splide__arrow--next"
>
Next
<
/
button
>
<
/
div
>
<
/
Splide
>
Svelte
<Splide hasTrack={ false } aria-label="..."> <SplideTrack> <SplideSlide>...</SplideSlide> </SplideTrack> <div class="splide__arrows"> <button class="splide__arrow splide__arrow--prev">Prev</button> <button class="splide__arrow splide__arrow--next">Next</button> </div> </Splide>
In the same way, you can add an autoplay toggle button and progress bar like so:
<
Splide
hasTrack
=
{
false
}
aria-label
=
"..."
>
<
SplideTrack
>
<
SplideSlide
>
...
<
/
SplideSlide
>
<
/
SplideTrack
>
<
div
class
=
"splide__progress"
>
<
div
class
=
"splide__progress__bar"
/
>
<
/
div
>
<
button
class
=
"splide__toggle"
type
=
"button"
>
<
span
class
=
"splide__toggle__play"
>
Play
<
/
span
>
<
span
class
=
"splide__toggle__pause"
>
Pause
<
/
span
>
<
/
button
>
<
/
Splide
>
Svelte
<Splide hasTrack={ false } aria-label="..."> <SplideTrack> <SplideSlide>...</SplideSlide> </SplideTrack> <div class="splide__progress"> <div class="splide__progress__bar" /> </div> <button class="splide__toggle" type="button"> <span class="splide__toggle__play">Play</span> <span class="splide__toggle__pause">Pause</span> </button> </Splide>
...or:
<
Splide
hasTrack
=
{
false
}
aria-label
=
"..."
>
<
div
class
=
"custom-wrapper"
>
<
button
class
=
"splide__toggle"
type
=
"button"
>
<
span
class
=
"splide__toggle__play"
>
Play
<
/
span
>
<
span
class
=
"splide__toggle__pause"
>
Pause
<
/
span
>
<
/
button
>
<
div
class
=
"splide__progress"
>
<
div
class
=
"splide__progress__bar"
/
>
<
/
div
>
<
SplideTrack
>
<
SplideSlide
>
...
<
/
SplideSlide
>
<
/
SplideTrack
>
<
/
div
>
<
/
Splide
>
Svelte
<Splide hasTrack={ false } aria-label="..."> <div class="custom-wrapper"> <button class="splide__toggle" type="button"> <span class="splide__toggle__play">Play</span> <span class="splide__toggle__pause">Pause</span> </button> <div class="splide__progress"> <div class="splide__progress__bar" /> </div> <SplideTrack> <SplideSlide>...</SplideSlide> </SplideTrack> </div> </Splide>
Props
The <Splide>
component accepts general HTML attributes — such as class
and aria-label
— and passes them to the carousel root element.
<
Splide
class
=
"my-carousel"
aria-label
=
"My Favorite Images"
>
<
/
Splide
>
Svelte
<Splide class="my-carousel" aria-label="My Favorite Images"> </Splide>
Additionally, it takes a few more props.
options
options: Options
Splide
options as an object:
<
Splide
options
=
{
{
rewind
:
true
,
width
:
800
,
gap
:
'1rem'
,
}
}
>
<
/
Splide
>
Svelte
<Splide options={ { rewind: true, width : 800, gap : '1rem', } } > </Splide>
This property is reactive, which means if you change values, the component will also update your carousel. But do not change readonly options, or the carousel will be broken.
extensions
extensions: Record<string, ComponentConstructor>
Registers extensions as an object literal.
transition
transition: ComponentConstructor
Registers the custom transition component.
hasTrack
hasTrack: boolean
Determines whether to render a track or not.
Events
You can listen to all Splide events through the Splide component. The event is generated by the original name with converting the format to the camelcase and removing colons. For example, "arrows:mounted" becomes "arrowsMounted". You can see the event list in this file.
<
Splide
on
:
arrowsMounted
=
{
e
=>
{
console
.
log
(
e
.
detail
.
prev
)
}
}
>
Svelte
<Splide on:arrowsMounted={ e => { console.log( e.detail.prev ) } }>
Because the Svelte event handler does not accept multiple arguments,
all parameters from the Splide event are packed into the detail
object.
It also contains the splide
instance itself.
For example, the detail
of the on:arrowsMounted
event includes splide
, prev
and next
properties.
Accessing Splide Instance
You can access the splide instance from this
:
<
Splide
bind:this
=
{
mySlider
}
>
...
<
/
Splide
>
Svelte
<Splide bind:this={ mySlider }> ... </Splide>
After Svelte mounts the Splide
component, the splide instance is available on mySlider.splide
.
onMount
(
(
)
=>
{
console
.
log
(
mySlider
.
splide
)
;
}
)
;
Svelte
onMount( () => { console.log( mySlider.splide ); } );
Example
Here is a small example:
12345678910111213<
script
>
import
{
Splide
,
SplideSlide
}
from
'@splidejs/svelte-splide';
import
'@splidejs/splide/dist/css/themes/splide-default.min.css';
<
/
script
>
<
Splide
options
=
{
{
rewind
:
true
}
}
aria-label
=
"My Favorite Images"
>
<
SplideSlide
>
<
img
src
=
"image1.jpg"
alt
=
"Image 1"
/
>
<
/
SplideSlide
>
<
SplideSlide
>
<
img
src
=
"image2.jpg"
alt
=
"Image 2"
/
>
<
/
SplideSlide
>
<
/
Splide
>
Svelte
<script> import { Splide, SplideSlide } from '@splidejs/svelte-splide'; import '@splidejs/splide/dist/css/themes/splide-default.min.css'; </script> <Splide options={ { rewind: true } } aria-label="My Favorite Images"> <SplideSlide> <img src="image1.jpg" alt="Image 1"/> </SplideSlide> <SplideSlide> <img src="image2.jpg" alt="Image 2"/> </SplideSlide> </Splide>
You can see working examples in this page and their sources here:
Migrating from v3
To migrate from v3 to v4:
- Read Breaking Changes
- If those changes affect your carousel, modify your code according to the migration guide except for "Slider Element"
- If you are using "Slider Element" or removed slots, restructure your component as described here
- Make sure to update CSS (now short paths are available, but old ones still work)
- Optionally, translate newly added texts by the
i18n
option - Optionally, add
aria-label
oraria-labelledby
to each carousel
Here is the list of removed slots:
before-track
after-track
before-slider
after-slider