slider-pro-js: Responsive Touch Slider With Thumbnail Navigation

slider-pro-js is a vanilla JavaScript slider library for responsive image galleries and content carousels.

It supports swipe navigation, multi-slide layouts, and thumbnail strips with images, text, or HTML content.

Features

• Horizontal, vertical, and right-to-left slide navigation.
• Infinite looping, autoplay, and fade transitions.
• Full-width, full-window, and fullscreen viewing modes.
• Touch, mouse, and keyboard controls.
• Configurable thumbnail placement and navigation arrows.
• Animated or static text and HTML layers.
• Responsive breakpoints and variable-size slides.
• Lazy-loaded images and high-density image sources.
• Automatic playback handling for video slides.
• URL hashes for opening individual slides.

How To Use It

Installation

Load the compiled stylesheet and the core script from a CDN.

<link rel="stylesheet" href="https://unpkg.com/[email protected]/build/slider-pro.css">
<script src="https://unpkg.com/[email protected]/build/slider-pro.js"></script>

Basic Usage

Create the .slider-pro element with a .sp-slides container. Each .sp-slide is one slide, and .sp-image identifies a slide’s main image.

<div id="photo-slider" class="slider-pro">
  <div class="sp-slides">
    <div class="sp-slide">
      <img class="sp-image" src="images/coast.jpg" alt="Rocky coastline">
    </div>
    <div class="sp-slide">
      <img class="sp-image" src="images/mountains.jpg" alt="Mountain range">
    </div>
    <div class="sp-slide">
      <img class="sp-image" src="images/forest.jpg" alt="Forest trail">
    </div>
  </div>
</div>
<script>
const slider = new SliderPro('#photo-slider', {
  width: 900,
  height: 500,
  arrows: true,
  buttons: true,
  autoplay: false
});
</script>

npm Package and Bundlers

For a modern web project, use the following imports with the #photo-slider markup from Basic Usage.

npm install slider-pro-js

import SliderPro, { Autoplay, Buttons, TouchSwipe } from 'slider-pro-js';
import 'slider-pro-js/css';
const slider = new SliderPro('#photo-slider', {
  addOns: [Autoplay, Buttons, TouchSwipe],
  width: 900,
  height: 500
});

Browser ES Module

The jsDelivr ES module endpoint is another installation option. Use the stylesheet and #photo-slider markup from Basic Usage. Put this import inside a <script type="module"> element after the markup in place of the browser-build initialization.

import SliderPro, { Autoplay, Buttons, TouchSwipe } from
  'https://cdn.jsdelivr.net/npm/[email protected]/+esm';
new SliderPro('#photo-slider', {
  addOns: [Autoplay, Buttons, TouchSwipe]
});

Create a Gallery With Thumbnails

Place the .sp-thumbnails container after .sp-slides. The two images in this example have matching thumbnail images. You can also place a .sp-thumbnail inside each slide or use HTML content in a thumbnail.

<div id="gallery" class="slider-pro">
  <div class="sp-slides">
    <div class="sp-slide">
      <img class="sp-image" src="images/item-1.jpg" alt="First product view">
    </div>
    <div class="sp-slide">
      <img class="sp-image" src="images/item-2.jpg" alt="Second product view">
    </div>
  </div>
  <div class="sp-thumbnails">
    <img class="sp-thumbnail" src="images/item-1-thumb.jpg" alt="View one">
    <img class="sp-thumbnail" src="images/item-2-thumb.jpg" alt="View two">
  </div>
</div>

const gallery = new SliderPro('#gallery', {
  width: 800,
  height: 450,
  autoplay: false,
  thumbnailsPosition: 'bottom',
  thumbnailWidth: 110,
  thumbnailHeight: 70,
  thumbnailArrows: true
});

Change Settings at Responsive Breakpoints

Replace the gallery initialization above with this configuration to move the thumbnail strip below the slider on narrow screens. Each breakpoint starts from the original settings. Repeat values that must apply at multiple widths.

const gallery = new SliderPro('#gallery', {
  width: 960,
  height: 480,
  thumbnailsPosition: 'right',
  thumbnailWidth: 120,
  breakpoints: {
    800: {
      thumbnailsPosition: 'bottom',
      thumbnailWidth: 100
    },
    500: {
      thumbnailsPosition: 'bottom',
      thumbnailWidth: 65,
      thumbnailHeight: 50
    }
  }
});

Display Animated Text Layers

Insert elements with the .sp-layer class inside a slide. Use layer data attributes for positioning, animation direction, and delays. The .sp-black, .sp-padding, and .sp-rounded classes apply the included layer styles. If the slider width is percentage-based and you need proportional layer scaling, specify a numeric autoScaleReference.

<div class="sp-slide">
  <img class="sp-image" src="images/city.jpg" alt="City skyline at dusk">
  <h2 class="sp-layer sp-black sp-padding sp-rounded"
      data-position="bottomLeft"
      data-horizontal="24"
      data-vertical="24"
      data-show-transition="left"
      data-show-duration="500"
      data-hide-transition="right">
    Explore the city
  </h2>
</div>

Lazy-Load Images and Supply Responsive Sources

For the built-in lazy-loading module, place a placeholder in src and the real image in data-src. data-small, data-medium, and data-large select alternative images at the configured slider-width thresholds. Native srcset is also available for responsive image markup.

<div class="sp-slide">
  <img class="sp-image"
       src="images/placeholder.gif"
       data-src="images/landscape.jpg"
       data-small="images/landscape-small.jpg"
       data-medium="images/landscape-medium.jpg"
       data-large="images/landscape-large.jpg"
       alt="Landscape at sunrise">
</div>

Display Video Slides

Use .sp-video for an HTML5 video or a YouTube, Vimeo, or Video.js player. Slider Pro expects enablejsapi=1 on a YouTube iframe and api=1 on a Vimeo iframe for its player integration.

<div class="sp-slide">
  <video class="sp-video" controls preload="none"
         poster="images/video-poster.jpg" width="800" height="450">
    <source src="media/demo.mp4" type="video/mp4">
  </video>
</div>

Control Slides and Listen for Changes

Use the slider instance from Basic Usage for additional controls. Place this button after the slider element. Slide indexes start at 0, and event.detail includes the selected and previous indexes for gotoSlide.

<button id="next-photo" type="button">Next photo</button>

slider.addEventListener('gotoSlide', (event) => {
  console.log('Selected slide:', event.detail.index);
});
document.querySelector('#next-photo').addEventListener('click', () => {
slider.nextSlide();
});

Configuration Options

Pass an options object as the second argument to new SliderPro(selector, options).

Core Sizing and Layout

Modules, Motion, and Navigation

Layers, Images, Thumbnails, and Video

Public Methods

Events

Register slider events with addEventListener() on the instance.

HTML Classes and Data Attributes

Slide and Thumbnail Markup

Layer Styling Classes

Layer Data Attributes

Use these attributes on elements with .sp-layer. data-position accepts topLeft, topCenter, topRight, bottomLeft, bottomCenter, bottomRight, centerLeft, centerRight, and centerCenter. The default is topLeft. Transition directions accept left, right, up, and down.

Image Source Attributes

CSS Module Imports

The npm package exports its complete stylesheet through slider-pro-js/css. The following public imports are available when a bundler can process CSS imports. Only import the module styles your project uses, along with the core stylesheet.

Available Modules

The npm entry point exports the following add-on classes. The compiled browser build includes all of them. Pass the desired class constructors in addOns when importing the JavaScript as modules.

Alternatives & Related Resources

• Create Modern Mobile-friendly Carousels With Slickless.js
• Modern Image Carousel with Thumbnail Transitions
• Vanilla JS Carousel Slider With Modern Look and Auto-Play
• Create A Responsive Keyboard-Accessible Image Carousel with JavaScript