Getting Started

基本的な使い方

インストール

Splideを導入するには、以下に示す4つの方法があります。

NPM

NPMを利用して最新版をインストールしてください（推奨）。

$ npm install @splidejs/splide

$ npm install @splidejs/splide

ホスティング

ファイルをサーバに直接配置してインストールします。以下のリンクからパッケージをダウンロードしてください。

ダウンロード

dist/jsディレクトリ下にあるsplide.min.jsファイルを<script>で読み込みます。

<script src="path-to-the-file/splide.min.js"></script>
HTML

<script src="path-to-the-file/splide.min.js"></script>

CDNの利用

自身のサーバにホストする代わりに、CDNからもファイルを参照できます。

jsDelivr

バージョンアップによる意図せぬ不具合を避けるため、本番用には"latest"キーワードを避け、特定のバージョン番号を指定することを強くおすすめします。

インテグレーション用パッケージ

React、VueまたはSvelteプロジェクトの場合、専用のインテグレーション用パッケージが用意されています。

最新版のVue Splideは、Vue 3のみサポートしています。古いバージョン（0.3.5）を使用すればVue 2で動作しますが、Splideのバージョンも古いため、おすすめしません。

CSSのインポート

使用するCSSファイルを選び、サイトに読み込みます。

読み込むファイルの選択

dist/cssあるいはdist/css/themesディレクトリの中に、いくつかのCSSがファイルが入っています。これらには以下のような違いがあります。

ファイル	説明
`splide.min.css`	すべてのスタイルが含まれています。内容は`splide-default.min.css`と同じです。
`splide-[theme].min.css`	すべてのスタイルが含まれています。
`splide-core.min.css`	スライダーを構築するための最低限のスタイルのみ含まれています。

スライダーの見た目を完全にカスタマイズしたい場合は、splide-core.min.cssを選ぶとよいでしょう。このファイルは必要最低限のスタイルしか含まれていないため、セレクタによる不要な上書き作業を避けることができます。そうでない場合は、splide.min.cssあるいはsplide-[theme].min.cssから選んでください。

スタイルシートへのリンク

ファイルを選んだら<link>タグを用いてサイトにリンクします。

<!-- サーバに置いたファイルを参照 -->
<link rel="stylesheet" href="path-to-the-file/splide.min.css">

<!-- またはCDN上のファイルを参照 -->
<link rel="stylesheet" href="url-to-cdn/splide.min.css">
HTML

<!-- サーバに置いたファイルを参照 -->
<link rel="stylesheet" href="path-to-the-file/splide.min.css">


<!-- またはCDN上のファイルを参照 -->
<link rel="stylesheet" href="url-to-cdn/splide.min.css">

バンドラがCSSに対応している場合は、スクリプトから直接読み込んでもかまいません。

// デフォルトのテーマ
import '@splidejs/splide/css';

// または、そのほかのテーマ
import '@splidejs/splide/css/skyblue';
import '@splidejs/splide/css/sea-green';

// あるいは、コアスタイルのみ
import '@splidejs/splide/css/core';
JavaScript

// デフォルトのテーマ
import '@splidejs/splide/css';


// または、そのほかのテーマ
import '@splidejs/splide/css/skyblue';
import '@splidejs/splide/css/sea-green';


// あるいは、コアスタイルのみ
import '@splidejs/splide/css/core';

HTML

次に、スライダーをHTMLで記述していきます。

HTMLの構成はおおまかに2種類存在し、配置するスライダーが直接ページのメインコンテンツと関係するかどうかによって決まります。たとえば、バナー、ギャラリー、商品一覧などのように、ページの主たるコンテンツの一部である場合は、以下のようなマークアップを記載してください。

<section class="splide" aria-label="Splideの基本的なHTML">
  <div class="splide__track">
		<ul class="splide__list">
			<li class="splide__slide">Slide 01</li>
			<li class="splide__slide">Slide 02</li>
			<li class="splide__slide">Slide 03</li>
		</ul>
  </div>
</section>
HTML

<section class="splide" aria-label="Splideの基本的なHTML">
  <div class="splide__track">
		<ul class="splide__list">
			<li class="splide__slide">Slide 01</li>
			<li class="splide__slide">Slide 02</li>
			<li class="splide__slide">Slide 03</li>
		</ul>
  </div>
</section>

もしスライダーが装飾目的であったり、あるいは直接メインコンテンツとはならない場合は（たとえば<aside>で記載されるような内容であるなら）、以下のマークアップを使用します。

<div class="splide" role="group" aria-label="Splideの基本的なHTML">
  <div class="splide__track">
		<ul class="splide__list">
			<li class="splide__slide">Slide 01</li>
			<li class="splide__slide">Slide 02</li>
			<li class="splide__slide">Slide 03</li>
		</ul>
  </div>
</div>
HTML

<div class="splide" role="group" aria-label="Splideの基本的なHTML">
  <div class="splide__track">
		<ul class="splide__list">
			<li class="splide__slide">Slide 01</li>
			<li class="splide__slide">Slide 02</li>
			<li class="splide__slide">Slide 03</li>
		</ul>
  </div>
</div>

.splide__slideクラスが付与された各スライドの中には、画像、テキストなどの任意のコンテンツを入れることができます。この構成では<section>、<ul>および<li>を用いていますが、<div>で置き換えても動作します。

どのような構成であっても、スライダーのルート要素には簡潔なラベルを付けてください。もしスライダーに対して適切な見出しが「目に見える形」で存在する場合は、aria-labelではなくaria-labelledbyで両者を関連付けてください。

<section class="splide" aria-labelledby="carousel-heading">
  <h2 id="carousel-heading">Splideの基本的なHTML</h2>

  <div class="splide__track">
		<ul class="splide__list">
			<li class="splide__slide">Slide 01</li>
			<li class="splide__slide">Slide 02</li>
			<li class="splide__slide">Slide 03</li>
		</ul>
  </div>
</section>
HTML

<section class="splide" aria-labelledby="carousel-heading">
  <h2 id="carousel-heading">Splideの基本的なHTML</h2>


  <div class="splide__track">
		<ul class="splide__list">
			<li class="splide__slide">Slide 01</li>
			<li class="splide__slide">Slide 02</li>
			<li class="splide__slide">Slide 03</li>
		</ul>
  </div>
</section>

より詳しい内容については、Structureを参照してください。

Splideの適用

最後に、記述したHTMLに対してSplideを適用します。

import文による導入

ESMの場合は、Splideクラスを読み込んでインスタンス化し、mount()メソッドを呼んでください。コンストラクタの引数には対象を特定するためのCSSセレクタ、あるいはエレメントそのものを渡します。

import Splide from '@splidejs/splide';

new Splide( '.splide' ).mount();
JavaScript

import Splide from '@splidejs/splide';


new Splide( '.splide' ).mount();

このとき、mount()を呼ぶのを忘れないようにしてください（忘れると何も表示されません😥）。

グローバル空間のSplideを使用

Splideを<script>で読み込んだ場合、どこからでもSplideクラスにアクセスできます。

<script>
  new Splide( '.splide' ).mount();
</script>
HTML

<script>
  new Splide( '.splide' ).mount();
</script>

初期化は、対象となる要素がすでにロードされている必要があります。<body>を閉じる直前に初期化処理を記載する場合は問題ありませんが、<head>など別の場所に記載する場合は、次のようにしてロードタイミングを監視してください。

<script>
  document.addEventListener( 'DOMContentLoaded', function() {
    var splide = new Splide( '.splide' );
    splide.mount();
  } );
</script>
HTML

<script>
  document.addEventListener( 'DOMContentLoaded', function() {
    var splide = new Splide( '.splide' );
    splide.mount();
  } );
</script>

複数のスライダー

Splideのインスタンスは、一つにつき一つのスライダーしか作れません。セレクタにクラス名を指定してコンストラクタに渡したとしても、Splideは最初にマッチした要素にしかスライダーを適用しません。複数のスライダーを作成する場合は、それぞれに対してインスタンスを作成してください。

new Splide( '#slider1' ).mount();

new Splide( '#slider2' ).mount();

new Splide( '#slider3' ).mount();
JavaScript

new Splide( '#slider1' ).mount();


new Splide( '#slider2' ).mount();


new Splide( '#slider3' ).mount();

まとめて初期化したい場合は、たとえば以下のようにforなどを利用してください。

var elms = document.getElementsByClassName( 'splide' );

for ( var i = 0; i < elms.length; i++ ) {
  new Splide( elms[ i ] ).mount();
}
JavaScript

var elms = document.getElementsByClassName( 'splide' );


for ( var i = 0; i < elms.length; i++ ) {
  new Splide( elms[ i ] ).mount();
}