slideswap

Minimal and performant fade slideshow written in pure JavaScript that leans as much as possible on CSS animations. Responsiveness is native, no resize listener. Uses your elements, doesn't detach them or clone them. Provided as ESM and IIFE.

Features

• No dependencies
• Small footprint
• CSS animations, transition duration is set in CSS
• ESM and IIFE
• Adaptive height (also animated)
• Responsive (no resize listener)
• Uses your elements, doesn't detach them or clone them
• Supports touch events (swipe) and mouse events (swipe simulation)
• Supports infinite loop
• Custom next and prev buttons
• No CLS (Cumulative Layout Shift) if you set initial classes and start from the first slide

Demo

https://stamat.github.io/slideswap/

Installation

NPM

npm install slideswap

Yarn

yarn add slideswap

Include the module in your project

import Slideswap from 'slideswap'; // If you have node_modules resolution, if not than add the path to the module

Include the SCSS file in your project or copy the styles from it, it's a very small CSS inside

@import 'slideswap'; // If you have node_modules resolution, if not than add the path to the SCSS file

CDN

<script src="https://unpkg.com/slideswap/dist/slideswap.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/slideswap/dist/slideswap.min.css">

Usage

Basic usage

<div id="slider-controls-1" class="slideswap-controls">
  <button class="js-slideswap-prev">Prev</button>
  <button class="js-slideswap-next">Next</button>
</div>
<div id="slider-1" class="slideswap-slides">
  <div class="slideswap-slide">Slide 1</div>
  <div class="slideswap-slide">Slide 2</div>
  <div class="slideswap-slide">Slide 3</div>
</div>

<script type="text/javascript">
  const slider = new Slideswap('#slider-1', {
    next: '#slider-controls-1 .js-slideswap-next',
    prev: '#slider-controls-1 .js-slideswap-prev',
    infinite: true
  });

  slider.element.addEventListener('slideswap:beforechange', (e) => {
    console.log(e.detail);
  });

  document.addEventListener('slideswap:beforechange', (e) => {
    console.log(e.detail);
  });

  slider.element.addEventListener('slideswap:change', (e) => {
    console.log(e.detail);
  });

  document.addEventListener('slideswap:change', (e) => {
    console.log(e.detail);
  });

  // slider.next(); - to go to the next slide
  // slider.previous(); - to go to the previous slide
  // slider.setCurrentSlide(index); - to go to a specific slide
  // slider.getCurrentSlide(); - to get the current slide index
  // slider.getNextIndex(); - to get the next slide index
  // slider.getPreviousIndex(); - to get the previous slide index
  // slider.getCurrentIndex(); - to get the current slide index
  // slider.getSlidesCount(); - to get the total number of slides
  // slider.destroy(); - to destroy the instance
  // slider.init(element, options); - to reinit the instance (if you have destroyed it)
</script>

The constructor accepts two arguments, the first one is the element or selector for the element and the second one is the options object.

new Slideswap(element, options);

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | infinite | Boolean | false | Whether or not the slideshow should loop infinitely | | activeClass | String | slideswap-current-slide | The class to apply to the current slide | | slideSelector | String | :scope > * | The selector for the slides | | start | Number | 0 | The index of the slide to start on | | adaptiveHeight | Boolean | true | Whether or not the slideshow should adapt to the height of the current slide | | next | HTMLElement or String | null | The element to use as the next button or selector for the next button | | prev | HTMLElement or String | null | The element to use as the previous button or selector for the previous button | | imageSelector | String | :scope > img | The selector for the images in the slides | | swipe | Boolean | true | Whether or not the slideshow should be swipeable | | swipeClass | String | slideswap-has-swipe | The class to apply to the slideshow when it is swipeable | | swipeActiveClass | String | slideswap-swipe-active | The class to apply to the slideshow when it is being swiped | | swipeThreshold | Number | 100 | The minimum distance the swipe must travel to trigger a slide change | | swipeTimeThreshold | Number | 1000 | The maximum amount of time the swipe can take to trigger a slide change in milliseconds. 0 disables this. |

Events

Events are triggered for each instance element and for the document. The event detail contains the object the target slide index and the previous slide index.

| Event | Description | | --- | --- | | slideswap:init | Fires after the instance is initialized. | | slideswap:beforechange | Fires before the slide changes. The event detail contains the current slide index and the next slide index. | | slideswap:change | Fires after the slide changes. The event detail contains the current slide index and the previous slide index. | | slideswap:destroy | Fires after the instance is destroyed. |

Methods

| Method | Description | | --- | --- | | next() | Goes to the next slide. | | prev() | Goes to the previous slide. | | setCurrentSlide(index) | Goes to a specific slide. | | getCurrentSlide() | Returns the current slide index. | | getNextIndex() | Returns the next slide index. | | getPreviousIndex() | Returns the previous slide index. | | getCurrentIndex() | Returns the current slide index. | | getSlidesCount() | Returns the total number of slides. | | add(slide, index) | Adds a slide. Slide parameter is an HTMLElement and index is insert before index and is optional | | remove(index) | Removes a slide. If index is not provided or invalid it will remove the last slide | | destroy() | Destroys the instance. | | init(element, options) | Reinitializes the instance. |

Public properties

| Property | Description | | --- | --- | | element | The instance element. | | options | The instance options. | | slides | The instance slides. | | currentIndex | The current slide index. |

TODO

• [ ] Add autoplay
• [ ] Add bullet navigation
• [ ] Add keyboard navigation
• [ ] Fix animation on current slide remove
• [ ] Wheel event support?