Option

オプション

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

オプションの変更方法

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

JavaScriptでの変更

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

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

データ属性による変更

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

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

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

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

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

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

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

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

オプション

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

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

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


type

type: string = 'slide'

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

'slide'

一般的なスライドアニメーションによるスライダー

'loop'

ループ(カルーセル)スライダー

'fade'

各スライドをフェードにより切り替える。このオプションはperPageと併用不可


rewind

rewind: boolean = false

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

speed

speed: number = 400

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


rewindSpeed

rewindSpeed: number

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

width

width: number | string

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

height

height: number | string

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


fixedWidth

fixedWidth: number | string

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

fixedHeight

fixedHeight: number | string

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


heightRatio

heightRatio: number

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

autoWidth

autoWidth: boolean = false

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

lazyLoadオプションと一緒に使用する場合は、各スライドが明示的なwidthの値を持っている必要があります。


autoHeight

autoHeight: boolean = false

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

lazyLoadオプションと一緒に使用する場合は、各スライドが明示的なheightの値を持っている必要があります。


start

start: number = 0

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

perPage

perPage: number = 1

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


perMove

perMove: number

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

clones

clones: number

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

このオプションがスライダーに対してどのような影響を与えるかよくわからない場合は、値を指定しないでください。


cloneStatus

cloneStatus: boolean = true

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


focus

focus: number | 'center'

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

gap

gap: number | string

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


padding

gap: number | string | { left?: number | string, right?: number | string } | { top?: number | string, bottom?: number | string }

水平スライダーの左右、あるいは垂直スライダーの上下の余白(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

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

  • 08
  • 09
  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09
  • 01
  • 02

arrows

arrows: boolean | 'slider' = true

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

true

ルート要素の直下に矢印を挿入する

false

矢印を無効にする

'slider'

スライダーエレメントの直下に矢印を挿入する


pagination

pagination: boolean | 'slider' = true

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

true

ルート要素の直下にページネーションを挿入する

false

ページネーションを無効にする

'slider'

スライダーエレメントの直下にページネーションを挿入する


easing

easing: string = cubic-bezier(0.25, 1, 0.5, 1)

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


easingFunc

easingFunc: ( t: number ) => number = t => 1 - Math.pow( 1 - t, 4 )

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


drag

drag: boolean | 'free' = true

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

true

ドラッグを有効にする

false

ドラッグを無効にする

'free'

フリードラッグモードを有効にする

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

noDrag

noDrag: string

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

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

dragMinThreshold

dragMinThreshold: number | { mouse: number, touch: number } = 10

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

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

この値は、ユーザが縦にスワイプしたいのか、スライダーを横にドラッグしたいのかを見極めるために重要な役割を果たします。touchの値は0を受け付けません。


flickPower

flickPower: number = 600

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


flickMaxPages

flickMaxPages: number = 1

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


waitForTransition

waitForTransition: boolean = true

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

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


arrowPath

arrowPath: string

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


autoplay

autoplay: boolean | 'pause' = false

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

Intersectionエクステンションを利用すると、スライダーがビューポート内にある場合にのみ自動再生を有効にできます。


interval

interval: number = 5000

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

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

pauseOnHover

pauseOnHover: boolean = true

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


pauseOnFocus

pauseOnFocus: boolean = true

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


resetProgress

resetProgress: boolean = true

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


lazyLoad

lazyLoad: boolean | 'nearby' | 'sequential' = false

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

false

遅延読み込みを無効にする

'nearby'

現在のページの周辺のスライドのみロードする

'sequential'

初期化後、最初のスライドから順番にロードする

遅延読み込みを使用するには、スライドの中の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

あるいは、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

preloadPages

preloadPages: number = 1

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

この値は、厳密にページ番号と連動しているわけではありませんperPage * ( preloadPages + 1 ) - 1という計算によって、単に「事前に何枚画像をロードするか」を決定するための範囲を決めるものです。たとえば、perPage2で現在のインデックスが0の場合、画像が読み込まれる範囲は[ -3, 3 ]と決定されます(マイナスのインデックスはクローンに対して有効です)。


keyboard

keyboard: boolean | 'focused' = true

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

true

documentkeydownイベントを監視する

false

キーボードによる操作を無効にする

'focused'

スライダーのルート要素にtabindex="0"を付加し、そのkeydownイベントを監視する

Intersectionエクステンションを利用すると、スライダーがビューポート内にある場合にのみキー入力を受け付けるように設定できます。


wheel

wheel: boolean = false

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


releaseWheel

releaseWheel: boolean = false

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

  • 01
  • 02
  • 03

direction

direction: 'ltr' | 'rtl' | 'ttb' = 'ltr'

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

'ltr'

左から右

'rtl'

右から左

'ttb'

上から下


cover

cover: boolean = false

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

このオプションはsrcsetをサポートしていません。


slideFocus

slideFocus: boolean = true

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


focusableNodes

focusableNodes: string = 'a, button, textarea, input, select, iframe'

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


isNavigation

isNavigation: boolean = false

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


trimSpace

trimSpace: boolean | 'move' = true

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

true

余白を取り除く。移動のリクエストが来た場合でも、アクティブスライドが更新されるのみで、スライダーそのものが動かない場合がでてくる

false

余白をそのまま表示する

'move'

余白を取り除くが、移動の要求が来た場合は必ずスライダーを動かす

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

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

  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09

updateOnMove

updateOnMove: boolean = false

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

  • 04
  • 05
  • 06
  • 07
  • 08
  • 09
  • 01
  • 02
  • 03
  • 04
  • 05
  • 06
  • 07
  • 08
  • 09
  • 01
  • 02
  • 03
  • 04
  • 05
  • 06

destroy

destroy: boolean | 'completely' = false

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

true

破棄するが、引き続きブレークポイントを監視する

'completely'

完全にスライダーを破棄する


mediaQuery

mediaQuery: 'min' | 'max' = 'max'

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


breakpoints

breakpoints: Record<string | number, ResponsiveOptions>

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

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

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

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

classes

classes: Record<string, string>

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

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

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


i18n

i18n: Record<string, string>

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