日本語

Svelte Splide

Introduction

Svelte Splide is a Svelte component for a Splide slider/carousel.

You are reading documentation for v0.2.0 or newer.

Installation

Get the latest version by NPM:

$ npm install @splidejs/svelte-splide

Usage

Components

Import Splide and SplideSlide components:

import { Splide, SplideSlide } from '@splidejs/svelte-splide';
JavaScript

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

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

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

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

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

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

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

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

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

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

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

After Svelte mounts the Splide component, the splide instance is available on mySlider.splide.

onMount( () => {
  console.log( mySlider.splide );
} );
Svelte

Example

Here is a small example:

<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

You can see working examples in this page and their sources here:

Migrating from v3

To migrate from v3 to v4:

  1. Read Breaking Changes
  2. If those changes affect your carousel, modify your code according to the migration guide except for "Slider Element"
  3. If you are using "Slider Element" or removed slots, restructure your component as described here
  4. Make sure to update CSS (now short paths are available, but old ones still work)
  5. Optionally, translate newly added texts by the i18n option
  6. Optionally, add aria-label or aria-labelledby to each carousel

Here is the list of removed slots:

  • before-track
  • after-track
  • before-slider
  • after-slider