Getting Started

基本的な使い方

v3用のドキュメントを参照しています

インストール

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に対応している場合は、スクリプトから直接読み込んでもかまいません。

HTML

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

基本構成

Splideのスライダーは、基本構成として以下のようなマークアップを必要とします。

<div class="splide">
  <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">
  <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クラスが付与された各スライドの中には、画像、テキストなどの任意のコンテンツを入れることができます。この構成ではスライドの記述に<ul>と<li>を用いていますが、<div>などのほかのタグも使用できます。ただし「セマンティックマークアップ」の観点からは、リストエレメントが望ましいと言えます。

もし画像スライダーを作成する場合は、coverオプションが便利です。このオプションはスライダの中の画像をbackground-imageに変換するため、画像編集ソフトなどでのクロップ作業をしなくてよくなります。

HTMLの拡張

以下のようなケースにおいて、追加のマークアップが必要になる場合があります。

独自の矢印ボタンを使用する場合
自動再生のプログレスバーや、再生・停止ボタンを配置する場合

詳細は、Arrows、Autoplay、または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();
}