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'

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


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である必要があります。詳しくはこのページを参照してください。


autoHeight

autoHeight: boolean = false

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


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

// 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である必要があります。


pagination

pagination: boolean | 'slider' = true

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


easing

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

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


easingFunc

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

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


drag

drag: boolean | 'free' = true

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

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

  • 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

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()を用いて手動で再生する必要があります。


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

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

遅延読み込みを使用するには、スライドの中の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'の時のみ有効なオプションです。


keyboard

keyboard: boolean | 'focused' = true

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


wheel

wheel: boolean = false

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


releaseWheel

releaseWheel: boolean = false

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

  • 01
  • 02
  • 03

direction

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

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


cover

cover: boolean = false

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


slideFocus

slideFocus: boolean = true

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


isNavigation

isNavigation: boolean = false

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


trimSpace

trimSpace: boolean | 'move' = true

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

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

  • 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

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


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>

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