ExamplesDocs

Documentation v5

Complete documentation of the installation and usage of the old version of Keen-Slider. You can find the latest documentation here.

Installation

Install keen-slider from npm.

npm install keen-slider@v5

Add as an module

import 'keen-slider/keen-slider.min.css'
import KeenSlider from 'keen-slider'

const slider = new KeenSlider('#my-keen-slider')

Add to HTML

<html>
  <head>
    <link
      rel="stylesheet"
      href="path/node_modules/keen-slider/keen-slider.min.css"
    />
  </head>
  <body>
    <div id="my-keen-slider" class="keen-slider">
      <div class="keen-slider__slide">1</div>
      <div class="keen-slider__slide">2</div>
      <div class="keen-slider__slide">3</div>
    </div>
    <script src="path/node_modules/keen-slider/keen-slider.js"></script>
    <script>
      var slider = new KeenSlider('#my-keen-slider')
    </script>
  </body>
</html>

Add as a React hook

import React from 'react'
import 'keen-slider/keen-slider.min.css'
import { useKeenSlider } from '@/hooks/use-keen-slider'

export default () => {
  const [sliderRef, slider] = useKeenSlider()

  return (
    <div ref={sliderRef}>
      <div class="keen-slider__slide">1</div>
      <div class="keen-slider__slide">2</div>
      <div class="keen-slider__slide">3</div>
    </div>
  )
}

Alternative: Add via CDN to HTML

<html>
  <head>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/keen-slider@latest/keen-slider.min.css"
    />
  </head>
  <body>
    <div id="my-keen-slider" class="keen-slider">
      <div class="keen-slider__slide">1</div>
      <div class="keen-slider__slide">2</div>
      <div class="keen-slider__slide">3</div>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/keen-slider@latest/keen-slider.js"></script>
    <script>
      var slider = new KeenSlider('#my-keen-slider')
    </script>
  </body>
</html>

API Reference

keen-slider needs a container to initialize. Optionally, you can pass some params to create your desired slider.

var slider = new KeenSlider('#my-slider', {
  loop: true,
  created: () => {
    console.log('created')
  },
  ...
})
  • container has to be from type HtmlElement or String (DOMString)
  • params has to be from type object, with options and event hooks (optional) returns a slider instance with some methods and getters

Options

breakpoints: object

Default: undefined

Change the options or event hooks for a given breakpoint. The breakpoint is set by the media query syntax. Note: The last options of the last matching breakpoint will be merged with the options on the root level. Example:

new KeenSlider('#my-slider', {
  loop: true,
  breakpoints: {
    '(min-width: 720px) and (max-width: 1000px)': {
      loop: false,
    },
  },
})

centered: boolean

Default: false

Active slide will be centered - only makes sense, when slidesPerView is greater than 1

controls: boolean

Default: true

Control slider with mouse or touch gestures

dragSpeed: number

Default: 1

Adjust the speed that is translated to the slider when dragging - minus values would invert the swipe direction

duration: number

Default: 500

Set the animation duration for the "snap"-mode

initial: number

Default: 0

Index of the initial activated slide

loop: boolean

Default: false

Infinite loop of slides

mode: "snap" | "free-snap" | "free"

Default: snap

Set the mode of movement of the slider

preventEvent: string

Default: "data-keen-slider-pe"

Name of the attribute that prevents the events from the slider on the element

resetSlide: boolean

Default: false

Reset to initial when the breakpoint changes

rtl: boolean

Default: false

Set the direction in which the slides are positioned to right-to-left

rubberband: boolean

Default: true

Simulate rubberband if moving or dragging above the slider edge

slides: DOMString | Function | HtmlElement[] | number

Default: ".keen-slider__slide"

  • DomString
  • Function, that return HtmlElement[]
  • HtmlElement[]
  • number - for custom sliders, see the examples for use cases

slidesPerView: number

Default: 1

Number of slides per view

spacing: number

Default: 0

Spacing between slides in pixel

vertical: boolean

Default: false

Set the slider direction to vertical

Event hooks

The following event hooks are available and can be set during initialization, just like the options. Every event hook comes with the instance of the slider.

Example:

new KeenSlider('#my-slider', {
  created: slider => {
    console.log(slider.track.details())
  },
})
  • afterChange - is fired after an animation is finished or the slider position is changed externally or internally
  • beforeChange - is fired before an animation is finished or the slider position is changed externally or internally
  • mounted - is fired after the slider is mounted to a container and the events are initialized
  • created - is fired after the slider has been initialized for the first time
  • slideChanged - is fired when the currently visible slide has changed
  • dragEnd - is fired when the dragging of the container has ended
  • dragStart - is fired when the dragging of the container has started
  • move - is fired every time the slider changes the position
  • destroyed - is fired after the slide is destroyed

Methods

controls

Paramater: active(boolean) Activate or deactivate touch or mouse controls of the slider

details

Returns the internal details of the slider. Example Return:

// zero point - left edge of the intended position of the active slide
{
  absoluteSlide: 100, // absolute index of the current slide - if loop is active, this number can be higher as the number slides or smaller the zero
  relativeSlide: 5, // relative index of the current slide - will be a number between 0 and the number of slides
  direction: 1, // last direction of slider movement: 1 | 0 | -1
  progressTrack: 0, // current progress of slider regarding to the track: 0 to 1
  progressSlides: 0, // current progress of slider regarding to the slides: 0 to 1
  positions: [ // position details of each slide
    {
      distance: 0, // relative distance to the start of the viewport, in relation to the width of the viewport
      portion: 1 // portion of visiblity of the slide - 0 to 1
    },
    ...
  ],
  position: 10000, // absolute position of the slider track (distance to the zero point) in px - length of the slider is infinite
  speed: 0, // current movement speed in px/ms
  size: 5, // number of slides
  widthOrHeight: 100 // width or height, if vertical, of the slider
}

moveToSlide

Paramater: slide(number) duration(number) Move to given slide (absolute slide - track is infinite when loop is active!) - optionally with the duration of the animation

moveToSlideRelative

Paramater: slide(number) nearest(boolean) duration(number) Move to given slide (relative slide - Range 0...n-1 - n is the number of slides)

  • nearest - move optionally in the direction of the nearest element (for the loop)
  • duration - set the duration of the animation, optionally

next

Move to next slide

prev

Move to previous slide

refresh

Paramater: options(object) Reinitialize slider and optionally overwrite options

resize

Manually trigger a resize - to recalculate width/height of slides or when a new slide was added

destroy

Remove events and styles set by the slider - refresh() would undo this