DOCSEARCHbyAlgolia
Submit Docs

Swiffy Slider

repository·main·Indexed 42 days ago

https://github.com/dynamicweb/swiffy-slider

A lightweight, touch-enabled HTML slider and carousel library (v2.1.2) that leverages native browser features like CSS scroll-snap and CSS Grid to minimize JavaScript footprint. It features a CSS-driven configuration system for layout, navigation, and animations, with an optional mouse drag extension and a programmatic API for advanced control.

Tokens
5.5K
Snippets
16
Records
25
Agent score
53%

What's inside Swiffy Slider

  1. How Swiffy Slider markup and configuration work

    main

    Swiffy Slider is a CSS-driven slider where all behavior and layout options are controlled by adding CSS classes to the wrapper element. It does not require JavaScript configuration for standard usage.

    Markup Structure

    A slider instance consists of a .swiffy-slider wrapper containing three optional sections:

    1. .slider-container: The scrollable container holding the slides.
    2. .slider-nav: Navigation buttons (previous and next). There should be exactly two.
    3. .slider-indicators: A container for indicator buttons (one per slide or per page).

    Basic Example

    <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>

  2. Migrating from v1 to v2

    main

    Swiffy Slider v2 introduces breaking changes to support ESM and improve performance. Key changes include:

    • ESM Only: v2 uses ES Modules. You must use <script type="module"> or an ESM-compatible bundler.
    • Manual Initialization: Auto-initialization is removed. You must explicitly call swiffyslider.init().
    • Named Exports: Instead of accessing window.swiffyslider, import the named export { swiffyslider } from 'swiffy-slider'.
    • API Changes: slideToByIndicator() now requires an event argument (intended for internal use). Use slideTo() for manual navigation instead.
    • Removed Attribute: The data-noinit attribute is no longer needed as the library never auto-initializes.
    • File Paths: Distribution file paths for JS and CSS have been simplified (e.g., dist/js/swiffy-slider.js and dist/css/swiffy-slider.css).
    <!-- v1 (Legacy) -->
<script src="swiffy-slider.min.js" defer></script>

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

  3. Initialize Swiffy Slider

    main

    Swiffy Slider v2 is ESM only. You can initialize it globally, on a specific element, or via dynamic import.

    Standard Initialization

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

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

    Initialize on a specific container (Performance optimization)

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

    Initialize a single slider

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

    Dynamic Import (Load on demand)

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

  4. Use Swiffy Slider with a bundler (ESM)

    main

    When using a modern bundler, import the swiffyslider object and the CSS directly. Remember to initialize the slider after the window has loaded.

    To add optional mouse drag support, you must also import and initialize swiffysliderextensions.

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

// For optional mouse drag support:
// import { swiffysliderextensions } from 'swiffy-slider/extensions';

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

  6. Quick start with Swiffy Slider

    main

    To get started with Swiffy Slider, follow these two steps:

    1. Add CSS and JS: Include the Swiffy Slider CSS and the ESM JavaScript module in your website's <head> section. You must call swiffyslider.init() after the window load event to bind the sliders.
    2. Add Markup: Use the required HTML structure with specific CSS classes to define the slider, container, navigation, and indicators.

    Note: The slider-item-helper class is used in the example to assist with layout, but the core functionality relies on .swiffy-slider, .slider-container, .slider-nav, and .slider-indicators.

    <!-- 1. Add CSS and JS to website head section -->
<script type="module">
    import { swiffyslider } from 'https://cdn.jsdelivr.net/npm/swiffy-slider@2.1.0/dist/js/swiffy-slider.js';
    window.addEventListener('load', () => swiffyslider.init());
</script>
<link href="https://cdn.jsdelivr.net/npm/swiffy-slider@2.1.0/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>

  7. Enable mouse drag support

    main

    Mouse drag is an optional extension. You must import and initialize both the core and the extensions module.

    1. Import swiffyslider and swiffysliderextensions.
    2. Call .init() on both.
    3. Add the .slider-nav-mousedrag class to your .swiffy-slider wrapper.
    import { swiffyslider } from 'swiffy-slider';
import { swiffysliderextensions } from 'swiffy-slider/extensions';

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

  8. Configure indicators

    main

    Add these classes to the .swiffy-slider wrapper to style the .slider-indicators container.

    CSS ClassDescription
    slider-indicators-roundChanges indicators to circles.
    slider-indicators-squareChanges indicators to squares.
    slider-indicators-outsideMoves indicators below the wrapper and increases wrapper height.
    slider-indicators-darkUses dark theme for indicators.
    slider-indicators-highlightIncreases the size of the active indicator.
    slider-indicators-smShows indicators on small devices (< 992px). Note: Do not use if showing multiple items per page on small devices.

  9. Configure navigation and autoplay

    main

    Add these classes to the .swiffy-slider wrapper to control navigation buttons and autoplay behavior.

    CSS ClassDescription
    slider-nav-pageSlides an entire page instead of a single slide when showing multiple items.
    slider-nav-noloopDisables looping (prev/next won't wrap around).
    slider-nav-nodelayDisables smooth scrolling for instant jumps.
    slider-nav-autoplayEnables automatic sliding. Default interval is 2500ms.
    slider-nav-autopausePauses autoplay on hover or touch.
    slider-nav-roundChanges arrows to a circular style.
    slider-nav-touchAlways shows navigation buttons on touch devices.
    slider-nav-visibleAlways shows navigation buttons (default is hover-only).
    slider-nav-outsideMoves buttons outside the wrapper (shrinks wrapper width).
    slider-nav-outside-expandMoves buttons outside using negative margins (wrapper size preserved).
    slider-nav-scrollbarMakes the .slider-container scrollbar visible.
    slider-nav-darkUses dark theme for navigation buttons.
    slider-nav-autohideHides arrows when the first/last slide is visible.

    Autoplay Interval: Use the data-slider-nav-autoplay-interval="ms" attribute on the wrapper to change the interval (default 2500, min 750).

  10. How slide visibility and indicators work

    main

    Swiffy Slider uses an IntersectionObserver to manage slide visibility and indicator states.

    Visibility Classes

    As slides enter or leave the viewport (relative to the .slider-container), the following classes are toggled:

    • .slide-visible: Applied to individual slides currently in view.
    • .slider-item-first-visible: Applied to the slider when its first child is visible.
    • .slider-item-last-visible: Applied to the slider when its last child is visible.

    You can adjust the visibility detection sensitivity using the data-slider-nav-animation-threshold attribute (defaults to 0.3).

    Indicators

    Indicators are managed via the .slider-indicators container. When a user clicks an indicator, slideToByIndicator calculates the correct slide index based on the indicator's position relative to its siblings and scrolls the slider. The handleIndicators method automatically updates the .active class on indicator elements as the user scrolls.

  12. Configure slide animations

    main

    To enable animations, add .slider-nav-animation to the wrapper, followed by an effect class.

    CSS ClassDescription
    slider-nav-animation-appearOpacity and scale (30% opacity, 90% scale).
    slider-nav-animation-fadeinOpacity fade (starts at 50%).
    slider-nav-animation-scaleScale up (starts at 90%).
    slider-nav-animation-scaleupScale up (starts at 25%).
    slider-nav-animation-turnRotateY (starts at 70deg).
    slider-nav-animation-slideupTranslateY (starts at 60% height).
    slider-nav-animation-zoomoutStarts at 130% scale and zooms down to normal.

    Animation Threshold: Use data-slider-nav-animation-threshold="0-1" on the wrapper to define when the animation starts (default 0.3).