オプション

オプションの変更方法

Splideはスライダーをカスタマイズするために、様々なオプションをとります。 これらは、次のような3つの方法を用いて変更できます。

JavaScriptでの変更

Splideのコンストラクタは、第2引数にオプションをとります。

new Splide( '.splide', {
  type   : 'loop',
  perPage: 3,
} );
JavaScript

new Splide( '.splide', {
  type   : 'loop',
  perPage: 3,
} );

データ属性による変更

data-splide属性を用いて、HTML側からオプションを指定できます。 このとき、属性の値にはJSONフォーマットを用います。

<div class="splide" data-splide='{"type":"loop","perPage":3}'>
</div>
HTML

<div class="splide" data-splide='{"type":"loop","perPage":3}'>
</div>

JSON内でダブルクォートを使用するため、上の例では、シングルクォートで属性の値を囲っています。 "によりJSONの値をエスケープすれば、属性にダブルクォートを用いることもできます。

コンストラクタ、データ属性両方でオプションが指定された場合、後者が前者を上書きますので注意してください。

静的プロパティによる変更（上級者向け）

複数のスライダーを作成する場合、共通のオプションを一括して設定したい場合がでてくるかもしれません。 このような場合、Splide.defaultsを用いて、デフォルトの値を設定できます。

Splide.defaults = {
  type   : 'loop',
  perPage: 2,
}
JavaScript

Splide.defaults = {
  type   : 'loop',
  perPage: 2,
}

この値はすべてのインスタンスから参照され、コンストラクタおよびデータ属性を用いて部分的に上書きできます。

オプション

オプションには、読み取り専用のオプションと、動的に変更可能なレスポンシブオプションの2種類が存在します。

レスポンシブオプションはbreakpointsを用いて更新したり、 あるいはSplide#optionsにオブジェクトを渡すことで、直接変更したりできます。 逆に、読み取り専用のオプションは変更しないでください。 これらは内部的にディスクリプタなどで保護されておらず、一見うまく更新できるように見える場合もありますが、 その動作は保証されたものではありません。

Splideが受け付けるオプションは次のリストの通りです。マークのついたものがレスポンシブオプションです。

type

スライダーの種類を指定します。

rewind

スライダーの終わりまで行ったときに、先頭に巻き戻せるかどうかを決定します。

speed

スライダーの移動時間をミリ秒単位で指定します。0を指定すると、アニメーションなしで直接対象に遷移します。

rewindSpeed

巻き戻す際の移動時間をミリ秒単位で指定します。指定しなかった場合は、speedの値が使用されます。

width

スライダーの最大幅を設定します。数字を指定した場合はピクセルとして扱われ、remや%などの相対単位も文字列として受け付けます。例えば、以下の例ではスライダーの幅を80%に指定しています。

height

スライダーの高さを設定します。数字を指定した場合はピクセルとして扱われ、%を除くremなどの相対単位も文字列として受け付けます。

fixedWidth

各スライドの幅を固定します。CSSの相対単位も利用できます。この値を設定した場合、perPageオプションは無視されます。

fixedHeight

各スライドの幅を固定します。%を除くCSSの相対単位も利用できます。この値を設定した場合、perPage、heightおよびheightRatioオプションは無視されます。

heightRatio

スライドの高さを、スライダーの幅に対する割合で指定します。例えば、スライドの幅が1000pxで割合に0.3を指定した場合、高さは300pxになります。ただし、heightやfixedHeightが与えられた場合、このオプションは無視されることに注意してください。

autoWidth

有効にすると、それぞれのスライドの幅がそのまま使用されます。このオプションを使用する場合は、perPageとperMoveオプションを与えないか、あるいは1である必要があります。詳しくはこのページを参照してください。

autoHeight

有効にすると、それぞれのスライドの高さがそのまま使用されます。このオプションを使用する場合は、perPageとperMoveオプションを与えないか、あるいは1である必要があります。詳しくはこのページを参照してください。

start

最初にアクティブになるスライドのインデックスを指定します。

perPage

1ページに何枚のスライドを表示するかを指定します。正の整数で指定し、小数の値は指定しないでください。

perMove

1度の移動で、何枚のスライドを移動するかを指定します。正の整数で指定し、小数の値は指定しないでください。

clones

ループスライダーを構築する際に生成される、クローンの数を明示的に指定します。

cloneStatus

is-activeクラスをクローンにも追加するかどうかを決定します。

focus

複数スライドがある場合、どのスライドをアクティブにするかを指定します。左右に出現する余白は以下のように取り除かれます。

trimSpaceオプションを変更することで、余白を表示できます。

gap

スライド間の余白を指定します。1emなどのCSSの相対単位も利用できます。

padding

水平スライダーの左右、あるいは垂直スライダーの上下の余白（Padding）を指定します。単一の値を指定すると、左右または上下に対して同じ値が適用されますが、オブジェクトを与えるとそれぞれ別の値を指定できます。1emなどのCSSの相対単位も利用できます。

// By number
padding: 10

// By the CSS format
padding: '1rem'

// Specifies each value for a horizontal slider
padding: { left: 10, right: 20 }
padding: { left: '1rem', right: '2rem' }

// Specified each value for a vertical slider
padding: { top: 10, bottom: 20 }
JavaScript

// By number
padding: 10


// By the CSS format
padding: '1rem'


// Specifies each value for a horizontal slider
padding: { left: 10, right: 20 }
padding: { left: '1rem', right: '2rem' }


// Specified each value for a vertical slider
padding: { top: 10, bottom: 20 }

例えばこの値を20%にすると、以下のような結果になります。

arrows

矢印ボタンを表示するかどうかを決定します。HTMLから独自の矢印を作成する場合でも、この値はtrueである必要があります。

pagination

ページネーションを表示するかどうかを決定します。

easing

linear, ease、cubic-bezier()など、CSSトランジションに使用するタイミング関数を指定します。

easingFunc

フリードラッグモードなどで使用する補間関数を指定します。

drag

ドラッグによりスライダーを動かせるかどうかを決定します。

フリードラッグモードでは特定のスライドにスナップしません。

noDrag

セレクタにより、ドラッグできない要素を指定します（^3.2.2）。

{
  noDrag: 'input, textarea, .no-drag',
}
JavaScript

{
  noDrag: 'input, textarea, .no-drag',
}

dragMinThreshold

ドラッグとみなされる最小移動距離を指定します。単一の値を与えると、タッチアクションに対してのみ作用しますが、オブジェクトを与えることでマウスに対しても最小距離を適用できます。たとえば、以下の2つの設定は同じ結果になります。

{
  dragMinThreshold: 10,
}

{
  dragMinThreshold: {
    mouse: 0,
    touch: 10,
  },
}
JavaScript

{
  dragMinThreshold: 10,
}


{
  dragMinThreshold: {
    mouse: 0,
    touch: 10,
  },
}

flickPower

フリックした際どのくらいの距離を移動するか決定するためのパラメータで、大きな数字を指定すればするほど遠くまで移動します。500程度の値が適当です.

flickMaxPages

フリックにより移動できる最大ページ数を指定します。

waitForTransition

スライダーが移動中にも操作を受け付けるかどうかを決定します。ただし、この値をfalseに指定したとしても、ループ中など、ある特定のタイミングでは操作を受け付けない場合があります。

また、wheelオプションを有効にする場合は、このオプションはfalseである必要があります（そうでないと一瞬で何枚も移動してしまいます）。

arrowPath

矢印に使われるSVGのパスを指定します。SVGのサイズは40×40です。

autoplay

自動再生を有効にするかどうかを決定します。'paused'を設定すると、自動再生は停止した状態から始まりますので、再生ボタンを提供するか、あるいはAutoplay#play()を用いて手動で再生する必要があります。

interval

自動再生の間隔をミリ秒単位で指定します。data-splide-intervalを使用すると、特定のスライドにおいてこの値を上書きできます。

<li class="splide__slide" data-splide-interval="1000"></li>
<li class="splide__slide" data-splide-interval="10000"></li>
HTML

<li class="splide__slide" data-splide-interval="1000"></li>
<li class="splide__slide" data-splide-interval="10000"></li>

pauseOnHover

マウスオーバーしたときに自動再生を停止するかどうかを決定します。

pauseOnFocus

スライダー内にフォーカスされたエレメントがある場合、自動再生を停止するかどうかを決定します。アクセシビリティの観点から、この値はtrueのままにしておくことをおすすめします。

resetProgress

自動再生が中断されたのち再開する際、それまでの経過時間を維持するか破棄するかを決定します。

lazyLoad

スライダー内の画像を遅延読み込みするかどうかを決定します。

遅延読み込みを使用するには、スライドの中のimg要素にdata-splide-lazy属性を追加し、その値として画像ファイルへのパスやURLを指定する必要があります。このとき、src属性は空か、あるいはプレースホルダなど、本来の画像とは別の画像へのパスにする必要があります。

<li class="splide__slide">
  <img data-splide-lazy="path-to-the-image" alt="cat">
</li>

<!-- または -->
<li class="splide__slide">
  <img
    src="data:image/png;base64,..."
    data-splide-lazy="path-to-the-image"
    alt="cat"
  >
</li>
HTML

<li class="splide__slide">
  <img data-splide-lazy="path-to-the-image" alt="cat">
</li>


<!-- または -->
<li class="splide__slide">
  <img
    src="data:image/png;base64,..."
    data-splide-lazy="path-to-the-image"
    alt="cat"
  >
</li>

あるいは、data-splide-lazy-srcsetを用いてsrcsetを指定できます。

<li class="splide__slide">
  <img
    data-splide-lazy-srcset="600.jpg 600w, 1000.jpg 1000w"
    sizes="100vw"
    data-splide-lazy="1000.jpg"
		alt="cat"
  >
</li>
HTML

<li class="splide__slide">
  <img
    data-splide-lazy-srcset="600.jpg 600w, 1000.jpg 1000w"
    sizes="100vw"
    data-splide-lazy="1000.jpg"
		alt="cat"
  >
</li>

preloadPages

遅延読み込みの際、事前に何ページ分読み込むかを指定します。lazyLoadオプションが'nearby'の時のみ有効なオプションです。

keyboard

キーボード操作を有効にするかどうかを決定します。アクセシビリティの観点から、この値はtrueのままにしておくことをおすすめします。

wheel

マウスホイールによるスライダーの移動を有効にするかどうかを決定します。waitForTransitionオプションはtrueに設定してください。

releaseWheel

スライダーが最初または最後のスライドに到達した際にwheelイベントを開放し、つづけてページをスクロールできるようにします。

direction

スライダーの方向を指定します。

cover

画像のsrcをその親要素のbackground-imageに変換するかどうかを決定します。このオプションを使用するには、height、fixedHeightまたはheightRatioオプションのいずれかを与えてください。

slideFocus

見えているスライドに対してtabindex="0"を追加するかどうかを決定します。

focusableNodes

スライドの中にある、フォーカス可能な要素を取得するためのセレクタです。アクセシビリティのため、スライドが見えていないとき（aria-hidden="true"）、これらの要素にはtabindex="-1"が付与されます。より詳しい内容は このセクション に記載されています。

isNavigation

ほかのスライダーのナビゲーションとして、それぞれのスライドをクリック可能にするかどうかを決定します。スライダー同士を同期させるには、Splide#sync()を使用してください。

trimSpace

focus optionを有効にした際に現れる余白を取り除くかどうかを決定します。

デフォルトで、左右の余白は取り除かれる設定になっています。このとき、スライダーはアクティブスライドの更新を優先し、スライダー自体は移動しない場合があります。

このオプションを無効にすると、左右の余白はそのまま表示されます。

余白を取り除き、かつスライダーを必ず移動させるには、'move'を指定してください。結果は以下のようになります。

updateOnMove

is-activeクラスを移動前に更新するかどうかを決定します。

destroy

スライダーを破棄するかどうかを決定します。

mediaQuery

ブレークポイントの検出に用いられるメディアクエリに対して、min-width、max-widthのどちらを使うかを指定します。

breakpoints

それぞれのブレークポイントに対するレスポンシブオプションの集合です。たとえば、幅が640pxより小さくなった際、スライドの表示数を4枚から2枚に減らすには次のように設定します。

{
  perPage: 4,
  breakpoints: {
		640: {
			perPage: 2,
		},
  }
}
JavaScript

{
  perPage: 4,
  breakpoints: {
		640: {
			perPage: 2,
		},
  }
}

特定のブレークポイントでスライダーを破棄するには次のようにします。

{
  breakpoints: {
		640: {
			destroy: true,
		},
  }
}
JavaScript

{
  breakpoints: {
		640: {
			destroy: true,
		},
  }
}

classes

クラス名を追加するためのオブジェクトを指定します。たとえば、自動生成される矢印やページネーションに対してクラスを追加するには、次のようにします。

new Splide( '.splide', {
  classes: {
		// 矢印関連のクラスを追加
		arrows: 'splide__arrows your-class-arrows',
		arrow : 'splide__arrow your-class-arrow',
		prev  : 'splide__arrow--prev your-class-prev',
		next  : 'splide__arrow--next your-class-next',

		// ページネーション関連のクラスを追加
		pagination: 'splide__pagination your-class-pagination', // container
		page      : 'splide__pagination__page your-class-page', // each button
  },
} ).mount();
JavaScript

new Splide( '.splide', {
  classes: {
		// 矢印関連のクラスを追加
		arrows: 'splide__arrows your-class-arrows',
		arrow : 'splide__arrow your-class-arrow',
		prev  : 'splide__arrow--prev your-class-prev',
		next  : 'splide__arrow--next your-class-next',


		// ページネーション関連のクラスを追加
		pagination: 'splide__pagination your-class-pagination', // container
		page      : 'splide__pagination__page your-class-page', // each button
  },
} ).mount();

デフォルトのクラス名はSplide本体が参照するため削除せず、同時に指定してください。

i18n

ローカライズ用のテキストを変更するためのオブジェクトです。詳しくはこのページを参照してください。