Super fast carousel and slider with touch for optimized websites running in modern browsers.

Modern browser offers really good options these days to create much better user experience for sliders and carousels than existing libraries offer.

This project utilizes what is available in modern browsers resulting in a super lightweight and fast slider, greatly reducing the javascript footprint and increase performance to meet todays standards.

• Navigate with Touch, Keyboard, trackpad, pen and Mouse - because it is just browser scrolling
• Uses native browser scroll behavior, scroll-snap and CSS grid to provide the best mobile and touch experience
• Can run in CSS only mode - no js for even better performance
• SEO friendly - all content is in pure markup
• WCAG friendly - all content is in pure markup and can be annotated accordingly, supports tabbing, keyboard navigation, aria attributing and all what is needed.
• Setup is done in pure markup and css classes, no scripting required
• No js loading of slides, configuration or initialization
• Vanilla javascript, ESM only
• Very low overall footprint ~3.5kb in total (css+js gzip'ed)

• Quick start
  • 1. Add CSS and JS to website head section
  • 2. Add markup
• Additional installation options
• Why Swiffy Slider
• Features
• Browser support
• What's included
• Bugs and feature requests
• Documentation
  • Introduction
  • Markup structure
  • Slider options (CSS Classes)
    • Slider wrapper
    • Slider sections
    • Slider options
    • Navigation options
    • Indicator options
    • Animation options
    • Extensions
  • Javascript
  • Javascript loading and binding
  • TypeScript and IntelliSense
  • CSS variables
  • Safari smooth scrolling
• Limitations
• Migrating from v1
• Development
• Contributing
• Star gazers
• Examples of sites using Swiffy Slider
• Versioning
• Creators
• Copyright and license

Quick start

1. Add CSS and JS to website head section

<script type="module">
    import { swiffyslider } from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/js/swiffy-slider.js';
    window.addEventListener('load', () => swiffyslider.init());
</script>
<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/swiffy-slider.css" rel="stylesheet">

2. Add markup

<div class="swiffy-slider slider-item-helper">
    <ul class="slider-container">
        <li>Slide 1</li>
        <li>Slide 2</li>
        <li>Slide 3</li>
    </ul>

    <button type="button" class="slider-nav"></button>
    <button type="button" class="slider-nav slider-nav-next"></button>

    <div class="slider-indicators">
        <button class="active"></button>
        <button></button>
        <button></button>
    </div>
</div>

Call swiffyslider.init() after the DOM is ready to bind all .swiffy-slider instances.

Additional installation options

• Download the latest release
• Clone the repo: git clone https://github.com/dynamicweb/swiffy-slider.git
• Install with npm: npm install swiffy-slider
• Install with yarn: yarn add swiffy-slider

Loading via bundler (ESM)

import { swiffyslider } from 'swiffy-slider';
import 'swiffy-slider/css';

window.addEventListener('load', () => swiffyslider.init());

Loading extensions (optional mouse drag support)

import { swiffysliderextensions } from 'swiffy-slider/extensions';

window.addEventListener('load', () => swiffysliderextensions.init());

Read the Getting started page for examples, configuration options and a visual configurator.

Why Swiffy Slider

Most slider libraries ship a large JavaScript runtime that reimplements scrolling, snapping, and touch handling from scratch. Modern browsers already do all of this natively. Swiffy Slider is a thin layer of CSS and a small amount of JavaScript that wires up what the browser already provides.

| Library | JS size (gzip) | |---|---| | Swiper | ~40KB | | Splide | ~11KB | | Glide.js | ~7KB | | Swiffy Slider | ~1.3KB |

The result is better scroll performance (native momentum and snap), full accessibility via native focus/tab/keyboard, and no dependencies to maintain.

Features

• Carousel - Slide any content. Images, cards, videos, text, banners, posters, anything markup
• Carousel - Slide using touch, keyboard, mouse or navigation buttons
• Carousel - 1, 2, 3, 4, 5 or 6 slides visible in the slider wrapper
• Carousel - snap to start or center slide items
• Carousel - Slide one item or entire page on navigate when showing more than one
• Carousel - Partially reveal next and previous (optional) slide to indicate touch scroll is available
• Carousel - Loop to start when slides end
• Navigation - 7 built in navigation styles for next and previous navigation in light or dark mode, 14 in total
• Navigation - Overlay or outside navigation options
• Navigation - Show navigation arrows on hover or always. Show on desktop, but not touch
• Indicators - 3 built in indicator styles; pin, dots or squares in light or dark mode
• Indicators - Overlay or outside location of indicators
• Indicators - Navigate to slide by clicking indicator
• Auto play - Automatically slide with specified interval
• Auto pause - Stop playing when mouse is hovering carousel or touch is used
• Animation - Add animations when slides slide into view
• Animation - Choose between 6 different animations
• Animation - Use normal, fast or slow animations
• Scripting - Automatic or manual initialization of slider instances using swiffyslider.init or swiffyslider.initSlider
• Scripting - Execute scripts when an item is done sliding using swiffyslider.onSlideEnd
• Scripting - Start and stop automatic sliding using script

Browser support

Swiffy Slider requires CSS scroll-snap and CSS Grid, which are supported in all modern browsers. No IE support.

| Browser | Minimum version | |---|---| | Chrome | 69 | | Firefox | 99 | | Safari | 11 | | Edge | 79 |

What's included

Within the download you'll find the following directories and files. You'll see something like this:

swiffy-slider/
├── dist/
│   ├── css/
│   │   ├── swiffy-slider.css
│   │   ├── swiffy-slider.css.map
│   ├── js/
│   │   ├── swiffy-slider.js
│   │   ├── swiffy-slider.js.map
│   │   ├── swiffy-slider.d.ts
│   │   ├── swiffy-slider-extensions.js
│   │   ├── swiffy-slider-extensions.js.map
│   │   ├── swiffy-slider-extensions.d.ts
├── src/
│   ├── swiffy-slider.js
│   ├── swiffy-slider-extensions.js
│   ├── swiffy-slider.css

All distributed files are ESM. Source maps are included for use with browser developer tools.

Bugs and feature requests

Have a bug or a feature request? Check out the issues section and see if your issue or idea is already created. If your problem or idea is not addressed yet, please open a new issue.

Documentation

Swiffy slider documentation website is part of this repo and can be found in the docs folder. Visit the doc on our github documentation page

Introduction

Swiffy slider is a wrapper defined in html with slides, navigation and indicators as its children.

All options and behavior is controlled with css classes that is added to the wrapper. No js configuration.

The wrapper is the .swiffy-slider element - options to control layout and behavior of slides, navigation and indicators are added to this element.

Markup structure

The slider markup is a .swiffy-slider wrapper that has 3 sections.

• One .slider-container that contains the slides
• Two .slider-nav buttons that is navigation buttons previous and next (optional)
• One .slider-indicators that contains the indicators (optional)

<div class="swiffy-slider [slider options] [navigation options] [indicator options]" data-slider-nav-autoplay-interval="3000">
    <ul class="slider-container">
        <li>Slide 1</li>
        <li>Slide 2</li>
    </ul>

    <button type="button" class="slider-nav"></button>
    <button type="button" class="slider-nav slider-nav-next"></button>
    
    <div class="slider-indicators">
        <button class="active"></button>
        <button></button>                
    </div>    
</div>

This example uses ul>li for slides. Can also be i.e. div or other elements. This example uses button for navigation. Could also be divs, but cannot be ul>li as that would be nested. This example uses div>button for indicators but could be other elements, i.e. ul>li structure instead. Wether to use buttons or div for the navigating elements, depends on how WCAG needs to be handled.

Slider options (CSS Classes)

Options are the css classes that can be added to the .swiffy-slider element to control how the slider will look and behave. No config in JS or similar.

The example below use the .slider-item-show2 option to show 2 slides and .slider-item-reveal to reveal part of the next and previous slide. By adding additional classes behavior and layout is controlled.

Head over to the configurator to try all options

<div class="swiffy-slider slider-item-show2 slider-item-reveal">
    <ul class="slider-container">
        <li>Slide 1</li>
        <li>Slide 2</li>
        <li>Slide 3</li>
    </ul>
</div>

Slider wrapper

Change behavior and styles on slides, navigation and indicators by adding option css classes to the .swiffy-slider wrapper.

Slider sections

For possible child elements to the swiffy-slider wrapper. These sections adds slides, navigation and indicators

Slider options

For the swiffy-slider wrapper. The slider-item-* option classes affects the slides (The slider-container children)

Navigation options

For the swiffy-slider wrapper. The slider-nav-* option classes affects the slider-nav elements

Indicator options

For the swiffy-slider wrapper. The slider-indicators-* option classes affects the slider-indicators child elements

Animation options

For the swiffy-slider wrapper. The slider-nav-animation-* option classes affects the animation of slides when they slide into view.

Extensions

Mouse drag support is provided as an optional separate module to keep the core small.

Import and initialize alongside the main slider:

import { swiffyslider } from 'swiffy-slider';
import { swiffysliderextensions } from 'swiffy-slider/extensions';

window.addEventListener('load', () => {
    swiffyslider.init();
    swiffysliderextensions.init();
});

Then add the class to any slider wrapper that should support mouse drag:

Javascript

Import swiffyslider from the package and call init() to set up all sliders. All options and behavior is handled by CSS classes — using the methods directly is only needed for advanced scenarios.

Listening for sliding ends for a container

<script>
const sliderElement = document.getElementById('myslider');
swiffyslider.onSlideEnd(sliderElement, function() {
    console.log('Scrolling stopped');
});
</script>

Listening for sliding ends for a container and find visible slides

window.addEventListener('load', () => {
    const sliderElement = document.getElementById('myslider');
    swiffyslider.onSlideEnd(sliderElement, () => {
        const visibleSlideElements = getVisibleSlides(sliderElement);
        console.log(visibleSlideElements.map(s => s.innerText));
    });
});

function getVisibleSlides(sliderElement) {
    const container = sliderElement.querySelector('.slider-container');
    const gapWidth = parseInt(window.getComputedStyle(container).columnGap);
    return [...container.children].filter(slide => {
        const left = slide.getBoundingClientRect().left - container.getBoundingClientRect().left;
        const right = left + slide.offsetWidth - gapWidth;
        return left >= 0 && right <= container.offsetWidth;
    });
}

Javascript loading and binding

Swiffy Slider v2 is ESM only. Import and initialize in your entry point:

import { swiffyslider } from 'swiffy-slider';
import 'swiffy-slider/css';

window.addEventListener('load', () => swiffyslider.init());

To initialize only part of the page (e.g. skip header/footer for faster init):

window.addEventListener('load', () => {
    swiffyslider.init(document.getElementById('content'));
});

To initialize a single slider:

swiffyslider.initSlider(document.getElementById('myslider'));

Load on demand via dynamic import (e.g. when slider scrolls into view):

<script type="module">
window.addEventListener('load', () => {
    import('https://cdn.jsdelivr.net/npm/[email protected]/dist/js/swiffy-slider.js').then(({ swiffyslider }) => {
        swiffyslider.init();
    });
});
</script>

TypeScript and IntelliSense

The package ships TypeScript declaration files (.d.ts) for both the core and the extensions module. No @types/ package is needed.

TypeScript users get full type checking automatically:

import { swiffyslider } from 'swiffy-slider';
import { swiffysliderextensions } from 'swiffy-slider/extensions';

window.addEventListener('load', () => {
    swiffyslider.init();
    swiffysliderextensions.init();
});

JavaScript users with // @ts-check or VS Code's implicit type checking get full IntelliSense from the JSDoc annotations in the source without any extra setup.

CSS variables

The Swiffy Slider CSS is making use of a number of CSS variables that can be overriden to control behavior and styling

Slide sizes, ratios, navigation etc. can be controlled by overruling the variable on the .swiffy-slider instance or in custom css.

Example

<div class="swiffy-slider slider-item-reveal slider-item-ratio slider-nav-round slider-nav-visible" 
style="
--swiffy-slider-item-ratio:100/33.3;
--swiffy-slider-nav-light:lightcyan;
--swiffy-slider-nav-dark:darkolivegreen;
--swiffy-slider-nav-zoom:.85;
--swiffy-slider-item-reveal:25%;">

    <ul class="slider-container">
        <li>...</li>
    </ul>

    <button type="button" class="slider-nav"></button>
    <button type="button" class="slider-nav slider-nav-next"></button>

    <div class="slider-indicators">
        <button class="active"></button>
        <button></button>
        <button></button>
    </div>
</div>

Limitations

These limitations are known and intentionally there to keep this library small, fast and smooth.

• Scroll speed comes in 2 flavors - instant or 'smooth'. This is because that is what browsers support out of the box using CSS scroll-behavior. See MDN
• Does not support slides of uneven widths. The width is controlled by the width of the wrapper and can have 1-6 slides per page depending on configuration.
• Smooth scrolling is not supported out of the box in Safari (Before v 15.4) (iOS + Mac) but can be fixed using a polyfill. See polyfill
• RTL is untested but as the entire slider is just markup, it should be supported very well
• Works in 'modern' browsers from the last ~3 years only. No IE support or anything funny.

Use other sliders and carousels if these limitations is important in your project.

Migrating from v1

v2 is ESM only and removes auto-initialization. Here is what changed:

Script loading

<!-- v1 -->
<script src="swiffy-slider.min.js" defer></script>

<!-- v2 -->
<script type="module">
    import { swiffyslider } from 'swiffy-slider';
    window.addEventListener('load', () => swiffyslider.init());
</script>

No more window.swiffyslider — import the named export instead:

// v1
window.swiffyslider.init();

// v2
import { swiffyslider } from 'swiffy-slider';
swiffyslider.init();

data-noinit is removed — v2 never auto-initializes. Always call swiffyslider.init() yourself.

slideToByIndicator() now requires an event argument — this is called internally and you should not need to call it directly. Use slideTo() instead.

Dist file paths changed:

| v1 | v2 | |---|---| | dist/js/swiffy-slider.min.js | dist/js/swiffy-slider.js | | dist/js/swiffy-slider.esm.min.js | dist/js/swiffy-slider.js (same file) | | dist/css/swiffy-slider.min.css | dist/css/swiffy-slider.css |

npm package exports changed:

// v1
import { swiffyslider } from 'swiffy-slider'          // → src/swiffy-slider.esm.js
import 'swiffy-slider/css'

// v2
import { swiffyslider } from 'swiffy-slider'          // → dist/js/swiffy-slider.js
import { swiffysliderextensions } from 'swiffy-slider/extensions'
import 'swiffy-slider/css'

Development

# Install dependencies
npm install

# Build once (outputs to dist/ and docs/assets/)
npm run build

# Watch mode — rebuilds on every save
npm run watch

# Watch + local dev server at http://localhost:5501
npm run dev

Source files are in src/. The build is handled by build.js using esbuild (JS) and lightningcss (CSS) — no bundler config files needed. After each build, output is automatically copied to docs/assets/ so the local docs site reflects your changes immediately.

Contributing

See CONTRIBUTING.md for full details.

Open tasks you could help with:

• Svelte component wrapper
• Vue component wrapper
• React component wrapper

Thank you for your understanding.

Star gazers

Feel free to star this project and help spread the word.

Examples of sites using Swiffy Slider

Open an issue or reach out via @nicped on GitHub to have your site added to this list.

• Ärzte ohne Grenzen Österreich
• Swiffy slider documentation
• Dynamicweb Swift Ecommerce Starter

Versioning

See the Releases section of our GitHub project for changelogs for each release version of Swiffy Slider.

Creators

Nicolai Høeg Pedersen

• https://github.com/nicped

Dynamicweb

• https://github.com/dynamicweb

Copyright and license

Code and documentation copyright 2022 the Swiffy Slider Authors and Dynamicweb A/S Code released under the MIT License. Docs released under Creative Commons.