Scroll Snap Slider

Mostly CSS slider with great performance. See a demo on codepen.

Premise

This library is a shortcut to something I personally have to implement in almost every website. To keep it small (see badges above), there are no fancy features, no error handling.

However, with a clear API and the use of a ES6 class, it can provide a useful base for custom extensions.

What this module contains:

Example markup for a scroll-snap slider
SCSS default styling for a scroll-snap slider without scrollbars
ES6 class to slightly enhance functionality

Installing

npm install barthy-koeln/scroll-snap-slider 

yarn add barthy-koeln/scroll-snap-slider

Usage

HTML + CSS are enough for a working slider. You can use IDs and anchor links to create navigation buttons.

The ES6 class provided in this package augments the slider with a few events and methods.

Markup

Slides always have 100% width. You can add whatever markup inside.

  <div class="scroll-snap-slider example-slider">
    <div class="scroll-snap-slide">
      <img src="https://picsum.photos/id/1011/400/300" />
    </div>
    <div class="scroll-snap-slide">
      <img src="https://picsum.photos/id/1018/400/300" />
    </div>
  </div>

SCSS

@import '~scroll-snap-slider';

Additional Styles

Prevents page navigation on horizontal scrolling, i.E. on MacOS. [Support tables]

.scroll-snap-slider {
  overscroll-behavior: none;
}

Prevents scrolling past elements in the slider: [Support tables]

.scroll-snap-slide {
  scroll-snap-stop: always;
}

JavaScript

Default behaviour:

import { ScrollSnapSlider } from 'scroll-snap-slider'

const slider = new ScrollSnapSlider(document.querySelector(".example-slider"));

slider.addEventListener('slide-start', function(event){
  console.info(`Started sliding towards slide ${event.detail}.`)
})

slider.addEventListener('slide-pass', function(event){
  console.info(`Passing slide ${event.detail}.`)
})

slider.addEventListener('slide-stop', function(event){
  console.info(`Stopped sliding at slide ${event.detail}.`)
})

Advanced config:

import { ScrollSnapSlider } from 'scroll-snap-slider'

// Do not automatically attach scroll listener
const slider = new ScrollSnapSlider(document.querySelector(".example-slider"), false);

slider.scrollTimeout = 50 // Sets a shorter tiemout to detect scroll end

// Rounding Method
// Note: These methods depend on the direction of scrolling, hence the "next one" is crucial.
// When scrolling in the opposite direction, the effects are reversed.
// I have found this to an edge case, when Math.round timing was slighlty off for the first exploration of a web page.
slider.roundingMethod = Math.ceil // Trigger 'active' slide changes as soon as the next one is visible
slider.roundingMethod = Math.floor // Trigger 'active' slide changes only when the next one is fully visible

slider.listenerOptions = supportsPassive ? { passive: true } : false // test support for passive listeners first

// Now that we've set the listenerOptions, we can attach the listener
slider.attachListeners()

API

Method	Description
`slideTo(index: Number): void`	Scrolls to slide with at `index`.
`addEventListener(...)`	This is a shortcut for `slider.element.addEventListener(...)`.
`removeEventListener(...)`	This is a shortcut for `slider.element.removeEventListener(...)`.
`attachEventListeners()`	Enables the JS behaviour of this plugin. This is called in the constructor.
`destroy()`	Free resources and listeners. You can/should do `slider = null` after this.

Events

Events dispatched on the slider's element:

Event Name	Event Detail Type	Description
`slide-start`	`Number`	Dispatched when sliding starts toward slide at `event.detail`.
`slide-pass`	`Number`	Dispatched when sliding passes (crosses the threshold to) slide at `event.detail`. The threshold is defined/altered by the `roundingMethod`.
`slide-stop`	`Number`	Dispatched when sliding stopped at index `event.detail`, i.e. the last scroll event happened before `scrollTimeout` ms.

You can use the proxy methods addEventListener and removeEventListener to listen to them.

Public Properties

Property	Description
`slide: Number` (read only)	Currently active slide.
`element: Element` (read only)	The element passed into the constructor.
`slideScrollLeft` (read only)	the `element.scrollLeft` value of the currently active slide.
`scrollTimeout: Number`	Timeout delay in milliseconds used to catch the end of scroll events.

Support

Check out the support tables for CSS scroll snap. Note that it's up to you to inject potential vendor prefixes.

onlinebizsoft/scroll-snap-slider