Option

オプション

オプションの変更方法

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'

role

role: string = 'region'

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

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


label

label: string

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

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

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

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


labelledby

labelledby: string

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


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

rewindByDrag

rewindByDrag: boolean

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

  • 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などの相対単位を指定することも可能です。


padding

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

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

// 数値で指定(px)
padding: 10
// CSSフォーマットで指定
padding: '1rem'
// それぞれ個別に指定(水平スライダー)
padding: { left: 10, right: 20 }
padding: { left: '1rem', right: '2rem' }
// それぞれ個別に指定(垂直スライダー)
padding: { top: 10, bottom: 20 }
JavaScript

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

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

arrows

arrows: boolean = true

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


pagination

pagination: boolean = true

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


paginationKeyboard

pagination: boolean = true

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


paginationDirection

pagination: 'ltr' | 'rtl' | 'ttb'

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

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

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

snap

snap: boolean = false

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

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

noDrag

noDrag: string

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

{
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 | 'global' | 'focused' = false

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

キー説明
LTRでは前の、RTLでは次のページを表示
LTRでは前の、RTLでは次のページを表示
TTBで前のページを表示
TTBで次のページを表示

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

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

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

true
false
'global'
'focused'

wheel

wheel: boolean = false

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


wheelMinThreshold

wheelMinThreshold: number

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


wheelSleep

wheelSleep: number

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


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オプションのいずれかを与えてください。


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のどちらを使うかを指定します。


live

live: boolean = true

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


breakpoints

breakpoints: Record<string | number, ResponsiveOptions>

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

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

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

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

reducedMotion

reducedMotion: Options

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

{
speed : 0,
rewindSpeed: 0,
autoplay : 'pause',
}
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>

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