scroll-snap-slider

The slider requires a specific HTML structure and CSS import to function correctly.

HTML Markup

Use a <ul> with the class scroll-snap-slider as the container, and <li> elements with the class scroll-snap-slide for each slide.

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

CSS Setup

Import the default styles in your CSS file:

@import 'scroll-snap-slider/dist/scroll-snap-slider.css';

Recommended Additional Styles

To improve user experience, consider adding these styles:

1. Prevent page navigation on horizontal scroll (e.g., macOS):

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

2. Prevent scrolling past elements in the slider:

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

To create a custom plugin, extend the ScrollSnapPlugin class and implement the required methods.

Implementation Requirements

• constructor(config): Pass configuration to the parent.
• get id(): Return a unique string identifier for the plugin instance.
• enable(slider): Attach listeners and initialize plugin logic using the provided slider instance.
• disable(): Clean up resources and remove listeners.

export class CustomPlugin extends ScrollSnapPlugin {

  constructor (config) {
    super()
    this.config = config
  }

  get id () {
    return 'lubba-wubba-dub-dub'
  }

  enable (slider) {
    // Implementation logic
  }

  disable () {
    // Cleanup logic
  }
}

export class CustomPlugin extends ScrollSnapPlugin {

  /**
   * Pass any config here
   * @param {*} config
   */
  constructor (config) {
    super()

    this.config = config
  }

  /**
   * Chose a unique plugin name.
   * @return {String}
   */
  get id () {
    return 'lubba-wubba-dub-dub'
  }

  /**
   * Attach listeners, fetch DOM things, save reference to the slider
   * @param {ScrollSnapSlider} slider
   * @override
   */
  enable (slider) {
    // TODO method stub
  }

  /**
   * Free resources, remove listeners, ...
   * @override
   */
  disable () {
    // TODO method stub
  }
}

The ScrollSnapSlider class augments a slider element with events and methods. If you only need the CSS behavior, the JavaScript instance is optional.

Basic Usage

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

const element = document.querySelector('.example-slider')
const slider = new ScrollSnapSlider({ element })

Advanced Configuration

Pass an options object to the constructor to customize behavior:

• scrollTimeout: (Number) Sets the timeout to detect the end of a scroll.
• roundingMethod: (Function) Determines when slide-pass events are dispatched. Options include Math.round (center), Math.ceil (as soon as next is visible), or Math.floor (when next is fully visible).
• sizingMethod: (Function) A function that receives the slider instance and returns the width of a slide.

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

const slider = new ScrollSnapSlider({
  element: document.querySelector('.example-slider'),
  scrollTimeout: 50,
  roundingMethod: Math.round,
  sizingMethod (slider) {
    return slider.element.firstElementChild.offsetWidth
  }
})

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

const element = document.querySelector('.example-slider')
const slider = new ScrollSnapSlider({ element })

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}.`)
})

When initializing ScrollSnapSlider, you can provide the following configuration options:

Example of custom sizing and rounding:

const slider = new ScrollSnapSlider({
  element: container,
  scrollTimeout: 200,
  roundingMethod: Math.floor,
  sizingMethod: (slider) => {
    // Custom logic, e.g., average of all children widths
    return 300;
  }
});

Methods

• slideTo(index: Number): void: Scrolls to the slide at the specified index.
• addEventListener(...): Shortcut for slider.element.addEventListener(...).
• removeEventListener(...): Shortcut for slider.element.removeEventListener(...).
• destroy(): Frees resources and listeners. It is recommended to set slider = null after calling this.

Events

Events are dispatched on the slider's element. Use the proxy addEventListener to listen to them.

TypeScript Typing

To get proper typing for these events, augment the global HTMLElementEventMap:

declare global {
  interface HTMLElementEventMap {
    'slide-pass': CustomEvent<number>;
    'slide-stop': CustomEvent<number>;
    'slide-start': CustomEvent<number>;
  }
}

The ScrollSnapAutoplay plugin automatically advances slides at a specified interval. It includes built-in logic to temporarily disable autoplay when user interactions (like touchmove or wheel) are detected, preventing the slider from fighting against the user. After a specified timeoutDuration, autoplay will automatically re-enable.

Constructor Parameters

import { ScrollSnapAutoplay } from './lib/ScrollSnapAutoplay';

// Example: Autoplay every 5 seconds, wait 10 seconds after interaction before resuming
const autoplayPlugin = new ScrollSnapAutoplay(5000, 10000, ['touchstart', 'wheel']);

// Assuming 'slider' is your initialized ScrollSnap instance
slider.addPlugin(autoplayPlugin);