オプション

オプションの変更方法

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オプションを有効にしてください。

role

ルート要素に持たせるroleを指定します。値はランドマークロールまたはgroupである必要があります。デフォルト値の'region'を無効にする、すなわちルート要素にroleが割り当てられないようにするには、空のstringか、あるいはundefinedを設定します。

もしルート要素に<section>が使用されている場合、アクセシブルな名前を持った<section>は暗黙的にregionロールが割り当てられるため、このオプションは使用されません。詳しくはこちらを参照してください。

label

ルート要素に持たせるaria-labelを指定します。このオプションは、HTMLで設定した値を上書きます。

destroy後にラベルの値が不適切になる場合（たとえば、スライダーという言葉が入っているなどの場合）は、breakpointsを用いて適切なものに更新してください。

{
  label: 'スライダー', // HTMLで設定している場合は不要
  breakpoints: {
    640: {
      destroy: true,
      label  : 'ギャラリー', // destroyされた後に使用されるラベル
    }
  }
}
JavaScript

{
  label: 'スライダー', // HTMLで設定している場合は不要
  breakpoints: {
    640: {
      destroy: true,
      label  : 'ギャラリー', // destroyされた後に使用されるラベル
    }
  }
}

もしスライダーのラベルとして適切な見出しが目に見える形で存在する場合は、aria-labelではなくaria-labelledbyを用いて両者の関連付けを行ってください。

labelledby

ルート要素に持たせるaria-labelledbyを指定します。このオプションは、HTMLで指定した値を上書きます。

rewind

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

speed

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

rewindSpeed

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

rewindByDrag

ドラッグまたはスワイプ操作でもスライダーを巻き戻せるかどうかを決定します。rewindオプションを有効にしないと動作しません。

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の相対単位も利用できます。

// 数値で指定（px）
padding: 10

// CSSフォーマットで指定
padding: '1rem'

// それぞれ個別に指定（水平スライダー）
padding: { left: 10, right: 20 }
padding: { left: '1rem', right: '2rem' }

// それぞれ個別に指定（垂直スライダー）
padding: { top: 10, bottom: 20 }
JavaScript

// 数値で指定（px）
padding: 10


// CSSフォーマットで指定
padding: '1rem'


// それぞれ個別に指定（水平スライダー）
padding: { left: 10, right: 20 }
padding: { left: '1rem', right: '2rem' }


// それぞれ個別に指定（垂直スライダー）
padding: { top: 10, bottom: 20 }

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

arrows

矢印ボタンを表示するかどうかを決定します。矢印は、トラック要素の直前に挿入されます。HTMLから独自の矢印を作成する場合でも、この値はtrueである必要があります。

pagination

ページネーションを表示するかどうかを決定します。ページネーションはトラック要素の親要素に挿入（append）されますので、たいていの場合はトラックの直後に配置されます。

paginationKeyboard

ページネーションがフォーカスを持っている場合、専用のキーボードショートカットを有効にするかどうかを決定します。W3C Carousel Design Patternの要件を満たすには、有効にしておく必要のあるオプションです。

paginationDirection

明示的にページネーションの方向を指定します。これは単に見た目を変えるだけでなく、ページネーションのためのキーボードショートカットや、ARIA属性にも影響します。初期値はスライダーのdirectionがそのまま使用されます。

easing

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

easingFunc

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

drag

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

フリードラッグモードのスライダーは次のように動作します。

snap

ドラッグがfreeの場合でも、最も近いスライドにスナップするようになります。

noDrag

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

{
  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

自動再生を有効にするかどうかを決定します。'pause'を設定すると、自動再生は停止した状態から始まりますので、再生ボタンを提供するか、あるいは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

次のようなキーボード操作を有効にするかどうかを決定します。

'focused'が与えられた場合、古いバージョンではルート要素にtabindex="0"を与えていましたが、この機能は次の理由により廃止されました。

• tabindex="0"を非インタラクティブな要素に適用するのは避けることが推奨されている
• ルート要素はregionまたはgroupロールを持たせる必要があるが、それらはインタラクティブではない

また、ページネーションがフォーカスされている場合は、専用のショートカットが優先されます。

wheel

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

wheelMinThreshold

慣性スクロールなどによって生じる微量な変化量を無視するための閾値です。

wheelSleep

次のWheel入力を受け付けるまでのスリープ時間をミリ秒単位で指定します。このタイマーは、スライドの移動と同時にスタートします。

releaseWheel

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

direction

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

cover

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

slideFocus

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

focusableNodes

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

isNavigation

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

trimSpace

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

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

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

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

omitEnd

有効にすると、最終ページに到達した時点で、非アクティブなスライドが残っていたとしても「次へ」の矢印を無効化します。また、スライダーの移動を発生させないページネーションのボタンを省略します**（^4.1.0）。このオプションを使用するには、focusを明示的に与える必要がある**ことに注意してください。

このオプションは、fixedWidthやautoWidthに対しても効果を発揮します。

updateOnMove

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

destroy

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

mediaQuery

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

live

ライブリージョンを有効にします。 isNavigationオプションが有効の場合、ライブリージョンは常に無効化されます。

breakpoints

それぞれのブレークポイントに対するレスポンシブオプションの集合です。デフォルトではメディアクエリにmax-width（デスクトップファースト）を使用しますが、mediaQueryオプションでmin-width（モバイルファースト）に変更できます。

たとえば、幅が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,
		},
  }
}

reducedMotion

(prefers-reduced-motion: reduce)を検出した際に適用されるオプションを変更できます。詳細はこちらを参照してください。初期値は以下の通りです。

{
  speed      : 0,
  rewindSpeed: 0,
  autoplay   : 'pause',
}
JavaScript

{
  speed      : 0,
  rewindSpeed: 0,
  autoplay   : 'pause',
}

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

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