日本語

Vue Splide

Introduction

Vue Splide is a Vue 3 component for a Splide slider/carousel.

You are reading documentation for v0.6.0 or newer.

Installation

Get the latest version by NPM:

$ npm install @splidejs/vue-splide

Usage

Registration

Import the VueSplide plugin and install it into your app:

import { createApp } from 'vue';
import App from './App.vue';
import VueSplide from '@splidejs/vue-splide';


const app = createApp( App );
app.use( VueSplide );
app.mount( '#app' );
JavaScript

or locally import Splide and SplideSlide components:

<script>
import { Splide, SplideSlide } from '@splidejs/vue-splide';


export default defineComponent( {
  components: {
    Splide,
    SplideSlide,
  },
} );
</script>
Vue

...and render them like this:

<template>
  <Splide :options="{ rewind: true }" aria-label="My Favorite Images">
    <SplideSlide>
      <img src="image1.jpg" alt="Sample 1">
    </SplideSlide>
    <SplideSlide>
      <img src="image2.jpg" alt="Sample 2">
    </SplideSlide>
  </Splide>
</template>
Vue

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/vue-splide/css';


// or other themes
import '@splidejs/vue-splide/css/skyblue';
import '@splidejs/vue-splide/css/sea-green';


// or only core styles
import '@splidejs/vue-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 :has-track="false">
  <SplideTrack>
    <SplideSlide>...</SplideSlide>
  </SplideTrack>
</Splide>
Vue

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 :has-track="false" aria-label="...">
  <div class="custom-wrapper">
    <SplideTrack>
      <SplideSlide>...</SplideSlide>
    </SplideTrack>


    <div class="splide__arrows" />
  </div>
</Splide>
Vue

...or with custom arrows:

<Splide :has-track="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>
Vue

In the same way, you can add an autoplay toggle button and progress bar like so:

<Splide :has-track="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>
Vue

...or:

<Splide :has-track="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>
Vue

Props

options

options: Options

Splide options as an object:

<Splide :options="yourOptions"></Splide>
Vue

This property is reactive, which means if you change values, the component will also update the carousel. But do not change readonly options, or the carousel will be broken.

tag

tag: string = 'div'

Allows you to specify the tag name used for the root element. It should be 'div', 'section', 'header', 'footer' or 'nav'. Although the default value is 'div' for backward compatibility, 'section' is recommended.

If you are using header, footer, or nav, you have to provide the most appropriate landmark role together. Otherwise, your accessibility tree will be invalid.

<Splide :tag="section"></Splide>
Vue

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 name is generated by the original name with adding the "splide" prefix to avoid collision against native events. For example, "arrows:mounted" becomes "splide:arrows:mounted".

<Splide @splide:arrows:mounted="onArrowsMounted"></Splide>
Vue

Note that the handler always takes the splide instance as the first argument, and original arguments after it.

function onArrowsMounted( splide, prev, next ) {
  console.log( splide.length );
}
JavaScript

Accessing Splide Instance

You can access the splide instance though a Ref object.

<template>
  <Splide ref="splide">
    ...
  </Splide>
</template>


<script>
import { defineComponent, onMounted, ref } from 'vue';


export default defineComponent( {
  setup() {
    const splide = ref();


    onMounted( () => {
      if ( splide.value && splide.value.splide ) {
        console.log( splide.value.splide.length );
      }
    } );


    return {
      splide,
    }
  },
} );
</script>
Vue

After Vue mounts the Splide component, the splide instance is available on ref.value.splide.

Example

Here is a small example:

<template>
  <Splide :options="options" aria-label="My Favorite Images">
    <SplideSlide>
      <img src="image1.jpg" alt="Sample 1">
    </SplideSlide>
    <SplideSlide>
      <img src="image2.jpg" alt="Sample 2">
    </SplideSlide>
  </Splide>
</template>


<script>
import { Splide, SplideSlide } from '@splidejs/vue-splide';
import { defineComponent } from 'vue';


export default defineComponent( {
  components: {
    Splide,
    SplideSlide,
  },


  setup() {
    const options = {
      rewind: true,
      gap   : '1rem',
    };


    return { options };
  },
} );
</script>
Vue

You can see working examples at 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 removed slots below, 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:

  • beforeTrack
  • afterTrack
  • beforeSlider
  • afterSlider