DOCSEARCHbyAlgolia
Submit Docs

keen-slider

repository·master·Indexed 26 days ago

https://github.com/rcbyr/keen-slider

A lightweight (~5.5KB gzipped), high-performance, and library-agnostic touch slider carousel. Designed with a mobile-first approach, it supports multi-touch and native touch/swipe behavior across JavaScript, TypeScript, React, Vue, Angular, and React Native.

Tokens
6.4K
Snippets
17
Records
42
Agent score
89%

What's inside keen-slider

  2. Use KeenSlider in React

    master

    In React, use the useKeenSlider hook. The hook must be called at the top level of your component. It returns an array: the first item is a sliderRef to be attached to your container element, and the second item is the instanceRef containing the slider properties.

    Note: For ES modules, import from keen-slider/react.es.

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

export default () => {
  const [sliderRef, instanceRef] = useKeenSlider(
    {
      slideChanged() {
        console.log('slide changed')
      },
    },
    [
      // add plugins here
    ]
  )

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

  3. Initialize KeenSlider in JavaScript

    master

    After installing, import the CSS and the library. You can initialize KeenSlider by passing a container (CSS selector string, HTMLElement, or a function returning one) as the first argument. The second argument is an optional Options object, and the third is an optional array of Plugins.

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

var slider = new KeenSlider(
  '#my-slider',
  {
    loop: true,
    created: () => {
      console.log('created')
    },
  },
  [
    // add plugins here
  ]
)

  4. Use KeenSlider in Vue 3

    master

    In Vue 3, use the useKeenSlider function within the Composition API. It returns an array: the first item is a ref() for the container, and the second is a ref() containing the slider instance.

    Note: For ES modules, import from keen-slider/vue.es.

    <script>
  import { ref } from 'vue'
  import { useKeenSlider } from 'keen-slider/vue'

  export default {
    setup() {
      const [container, slider] = useKeenSlider({ loop: true }, [
        // add plugins here
      ])
      return { container }
    },
  }
</script>

<template>
  <div ref="container" class="keen-slider">
    <div class="keen-slider__slide number-slide1">1</div
    <div class="keen-slider__slide number-slide2">2</div
    <div class="keen-slider__slide number-slide3">3</div
    <div class="keen-slider__slide number-slide4">4</div
    <div class="keen-slider__slide number-slide5">5</div
    <div class="keen-slider__slide number-slide6">6</div
  </div>
</template>

<style>
  @import url('keen-slider/keen-slider.css');
</style>

  5. Use the useKeenSliderNative hook in React Native

    master

    The useKeenSliderNative hook is the primary way to implement a slider in React Native. It must be called at the top level of your component.

    • First argument: An optional Options object and Event hooks.
    • Second argument: Optional Plugins.
    • Returns: A slider instance containing containerProps for the parent container and slidesProps (an array) for each individual slide.

    Apply slider.containerProps to your wrapper View and slider.slidesProps[idx] to each slide View.

    import { useKeenSliderNative } from 'keen-slider/react-native'

export default () => {
  const slides = 4
  const slider = useKeenSliderNative({
    slides,
  })

  return (
    <View {...slider.containerProps}>
      {[...Array(slides).keys()].map(idx => {
        return (
          <View key={idx} {...slider.slidesProps[idx]}>
            <Text>Slide {idx}</Text>
          </View>
        )
      })}
    </View>
  )
}

  6. Install and use Keen-Slider

    master

    Keen-Slider is a lightweight (~5.5KB gzipped), library-agnostic slider library that works with JavaScript, TypeScript, React, Vue, Angular, and React Native. It is designed with a mobile-first approach, supporting multi-touch and native touch/swipe behavior.

    To get started, you can install the package via npm:

    npm install keen-slider

    For detailed implementation guides and specific framework integrations, refer to the official Documentation and Examples.

  9. Configure slides configuration

    master

    The slides option specifies how slides are configured. It can be:

    • number: Sets the total number of slides.
    • object:
      • origin: 'auto' | 'center' | number. Default is 'auto'.
      • number: number | function | null. Behaves like the top-level slides option.
      • perView: number | function | 'auto'. Determines slide size relative to viewport. Default is 1.
      • spacing: number | function. Pixel spacing between slides. Default is 0.
    • function: Returns an array of slide configurations. Each configuration object can have origin (number), size (number), and spacing (number). The function receives (containerSize, slidesArray) as arguments.
    • null: Slides are determined by the selector option.

  11. Configure Keen-Slider React Native Options

    master

    Customize the slider behavior using the Options object passed to useKeenSliderNative.

    Core Behavior

    • drag: boolean (Default: true). Enables/disables touch control.
    • dragSpeed: number | function (Default: 1). Speed applied during dragging. Negative values invert swipe direction.
    • initial: number (Default: 1). The index of the initially visible slide.
    • loop: boolean | object (Default: false). Enables carousel looping. If an object, you can set min and/or max indices.
    • mode: 'snap' | 'free' | 'free-snap' (Default: 'snap'). Animation applied after a drag ends.
    • rtl: boolean (Default: false). Enables right-to-left direction.
    • vertical: boolean (Default: false). Changes direction to vertical.
    • rubberband: boolean (Default: true). Enables/disables rubberband behavior during dragging.

    Animation & Range

    • defaultAnimation: object. Sets default animation for moveToIdx, next, and prev.
      • duration: number (ms).
      • easing: function ((time: number) => number).
    • range: object. Defines accessible slide range.
      • min: number.
      • max: number.
      • align: boolean (aligns max position to end of last slide).

    Slide Configuration (slides)

    Specifies how slides are configured. Can be a number, object, or function.

    • number: Sets the total number of slides.
    • object:
      • origin: 'auto' | 'center' | number (Default: 'auto').
      • perView: number | function (Default: 1).
      • spacing: number | function (Default: 0).
    • function: Receives containerSize as the first argument. Returns an array of slide configurations with:
      • origin: number (Default: 0).
      • size: number (Default: 1).
      • spacing: number (Default: 0).

  12. Configure selector for slides

    master
    The selector option specifies how slides are retrieved from the DOM. It accepts a css selector string, an array of HTMLElement, a function (receiving the container and returning an array of elements, a NodeList, etc.), or null. If set to null, the slider will not position or scale slides. Default is '.keen-slider__slide'.