SliderKit

SliderKit example

How it works

A slider of anything: pictures, cards, text or WebGL transitions, from one handler and one markup.

SliderKit moves a row of items with arrows, dots, touch or mouse drag, showing one or several at a time and a different number per breakpoint. It runs on three packages by the same author: @andresclua/sliderkit, the engine (layout, loop, touch, breakpoints, freeze), @andresclua/sliderkit-plugins, which adds the arrows, the pagination and the lifecycle hooks, and @andresclua/sliderkit-webgl, which replaces the slide transition with a GPU shader. The documentation and the repository cover the whole API; this page covers what the framework uses.

The class in src/js/handler/sliderkit maps six selectors to six configs: a standard slider, a text slider and four WebGL ones. Every config reads what it needs from data-* attributes on the element, so one handler serves every slider on the site. SliderKit.js is the class the Manager instantiates: it hands the options to the package and, when a config carries webglConfig, loads the WebGL plugin and the textures before building the slider.

The markup

A wrapper with the js--sliderkit hook and data-sliderkit-items, and one item per slide. The package wraps the element in its own .sliderkit__outer and .sliderkit__overflow, clones the items for the loop and injects the arrows and the dots. Its base SCSS is imported in style.scss; c--sliderkit-a adds the look of the items, the arrows and the dots. The SliderkitA component renders this markup from a slides prop.

<!-- The wrapper is the slider: the hook for the handler, and how many items are visible for the package -->
<div class="c--sliderkit-a">
  <div class="c--sliderkit-a__wrapper js--sliderkit" data-sliderkit-items="1">
    <div class="c--sliderkit-a__wrapper__item">…</div>
    <div class="c--sliderkit-a__wrapper__item">…</div>
    <div class="c--sliderkit-a__wrapper__item">…</div>
  </div>
</div>

The handler

The base config reads the number of visible items and the breakpoint overrides from the attributes, turns them into the package's responsive map and adds the three plugins. The loop clones the items when the slider mounts, and the Lazy handler only scans the DOM once, so the hooks plugin revalidates it on init and after every change, or the pictures in the clones would never load:

this.config = ({ element }) => {
    const responsive = {};
    const addBreakpoint = (width, attr) => {
        const value = parseInt(element.getAttribute(attr), 10);
        if (!isNaN(value)) responsive[width] = { items: value };
    };
    addBreakpoint(580,  "data-sliderkit-items-tablets");
    addBreakpoint(810,  "data-sliderkit-items-tabletm");
    addBreakpoint(1024, "data-sliderkit-items-tabletl");
    addBreakpoint(1300, "data-sliderkit-items-laptop");
    addBreakpoint(1570, "data-sliderkit-items-desktop");
    addBreakpoint(1700, "data-sliderkit-items-wide");

    const arrowsContainer = element.parentElement.querySelector(".js--sliderkit-arrows");

    return {
        items: parseInt(element.getAttribute("data-sliderkit-items")) || 1,
        loop: true,
        speed: 400,
        gutter: 32,
        mouseDrag: true,
        preventActionWhenRunning: true,
        responsive,
        plugins: [
            arrows(arrowsContainer ? { container: arrowsContainer } : {}),
            pagination({ type: "dots", clickable: true }),
            hooks({
                onInit: () => this.revalidateLazy(),
                afterChange: () => this.revalidateLazy(),
            }),
        ],
    };
};

What the framework does for you

Lazy loading. A standard or text slider is built when it gets within 30px of the viewport (Boostify, scroll method). The WebGL ones use a distance of 0: they preload textures and take the GPU, so they wait until they are in view. The package is imported once and cached by the Manager.
WebGL preload. SliderKit.js imports @andresclua/sliderkit-webgl on the first WebGL slider and keeps the module for the next pages. preloadWebGL turns the image paths into loaded HTMLImageElements, which the plugin needs before uploading them as textures; only then is the webgl plugin appended and the slider built:

if (this.webglConfig) {
    // Load once, reuse on subsequent page navigations
    if (!_webglModule) _webglModule = await import("@andresclua/sliderkit-webgl");
    const { webgl, preloadWebGL } = _webglModule;

    // Images must be loaded into HTMLImageElement before uploading as WebGL textures
    const assets = await preloadWebGL({
        slides:       this.webglConfig.slides,       // string[] — image paths
        displacement: this.webglConfig.displacement,  // string   — displacement map path
    });

    options.plugins = [
        ...(options.plugins || []),
        // effect: 'displacement' | 'custom' — see @andresclua/sliderkit-webgl docs
        webgl({
            effect: this.webglConfig.effect,
            assets,
            ...(this.webglConfig.frag     && { frag:     this.webglConfig.frag }),
            ...(this.webglConfig.duration !== undefined && { duration: this.webglConfig.duration }),
        }),
    ];
}

Page transitions. Every instance is destroyed before swup replaces the content, whichever of the six selectors is on the page, and rebuilt on the new one. SliderKit is registered with modifyHeight: true in resources.js.
Frozen arrows outside the slider. When a slider freezes (see Responsive and freeze), the package only hides the arrows inside its own wrapper. For arrows in a custom container, SliderKit.js reads slider.freeze on init and on every newBreakpointEnd and hides them itself.

Basic

One picture at a time, or three. The number of visible items is the only thing that changes.

Default items="1"items="3"

The default: data-sliderkit-items="1", arrows over the slides, dots under them, an infinite loop and mouse drag. The transition takes 400ms and, while it runs, further clicks and drags are ignored (preventActionWhenRunning). With data-sliderkit-items="3" three slides share the width, separated by the 32px gutter, and each step still moves one slide.

<!-- Three visible at once. Everything else is the same -->
<div class="c--sliderkit-a">
  <div class="c--sliderkit-a__wrapper js--sliderkit" data-sliderkit-items="3">
    <div class="c--sliderkit-a__wrapper__item">
      <img class="c--sliderkit-a__wrapper__item__media" src="…" alt="Slide 1" width="1600" height="900" loading="lazy">
    </div>
    …
  </div>
</div>

Live example

items="1"items="3"

One item

Three items

Responsive and freeze

A different number of items per breakpoint, and a slider that stops being one when everything fits.

Variation items="2"items-tabletl="4"freezable: true

data-sliderkit-items is the number of visible items from 0px up. Add a breakpoint suffix to change it from a width on: data-sliderkit-items-tablets (580px), -tabletm (810px), -tabletl (1024px), -laptop (1300px), -desktop (1570px) and -wide (1700px), the breakpoints of _vars.scss. The handler collects them into the package's responsive option, a map of min-width to options, and the package switches on resize. Each item here is a g--card-09 with a link; the track is a flex row, so cards with different amounts of text get the same height.

Freeze is what the package does when there is nothing to slide: with freezable on (the default), whenever the number of slides is less than or equal to the number of visible items the slider freezes. The outer wrapper gets sliderkit--frozen, the track stays at its first position, the base SCSS hides the arrows and the dots, and touch and drag do nothing. The items keep the width they would have in a running slider, so the layout does not jump. It is checked again at every breakpoint change, which gives three cases:

Six cards, 2 then 4 visible: a slider at every width.
Four cards, 2 then 4 visible: a slider on small screens, frozen from tabletl, where all four fit.
Two cards, 3 visible: frozen at every width, and each card keeps one third of the row.

<!-- 2 visible by default, 4 from tabletl (1024px). Each item is a g--card-09 -->
<div class="c--sliderkit-a">
  <div class="c--sliderkit-a__wrapper js--sliderkit" data-sliderkit-items="2" data-sliderkit-items-tabletl="4">
    <div class="c--sliderkit-a__wrapper__item">
      <div class="g--card-09">…</div>
    </div>
    …
  </div>
</div>

Live example

items="2"items-tabletl="4"freezable: true

Six cards, 2 then 4 visible

Auto Dealers

Coverage built around inventory, garage liability, and sales risk.

Attribute	Where	What it does
`data-sliderkit-items`	The slider	Visible items from 0px up. Defaults to `1` when missing or not a number
`data-sliderkit-items-tablets`, `-tabletm`, `-tabletl`, `-laptop`, `-desktop`, `-wide`	The slider	Visible items from that breakpoint on: 580, 810, 1024, 1300, 1570 and 1700px. Each one becomes an entry of `responsive`
`data-webgl-effect`	The WebGL slider	`displacement` (default), `rgb-shift`, `radial` or `custom`. Read by `configWebGL`; the other WebGL configs fix their effect in JS
`data-webgl-displacement`	The WebGL slider	Path of the greyscale displacement map. Needed by `displacement` only
`data-webgl-src`	Each WebGL slide	Path of the picture, uploaded as a texture. The slides are collected in DOM order
`data-title`	Each WebGL slide	Text written in the caption title by `configWebGL` when the slide becomes active

Option	Package default	What it does and what the configs set
`items`	`1`	Slides visible at once. From `data-sliderkit-items`; always `1` in the WebGL configs
`loop`	`false`	Infinite loop, done by cloning the slides. `true` in every config
`speed`	`300`	Transition duration in ms. `400` for the standard slider; `0` for text and WebGL, where the motion is GSAP's or the shader's
`gutter`	`0`	Gap between slides in px. `32` in the standard config
`mouseDrag`	`false`	Drag with the mouse, besides touch. `true` for standard and text, `false` for WebGL
`preventActionWhenRunning`	`false`	Ignores clicks and drags while a transition runs. `true` for standard and text
`responsive`	`{}`	Options per min-width, e.g. `{ 1024: { items: 4 } }`. Built from the breakpoint attributes
`freezable`	`true`	Not set by the configs: the package default. Freezes the slider when the slides are no more than the visible items
`plugins`	`[]`	The plugin instances, below

Plugin	Options used	What it does
`arrows()`	`container`	Previous and next buttons. Injected into the outer wrapper, or into `container` (an element or a selector) when given: the handler passes the `js--sliderkit-arrows` sibling. Also accepts `prevText`, `nextText` and `wrapper`
`pagination()`	`type: "dots"`, `clickable: true`	Dots under the slider, one per slide, that go to it on click. `type` can also be `fraction` or `progress`; `container` moves them
`hooks()`	`onInit`, `beforeChange`, `afterChange`	Lifecycle callbacks. `onInit({ slides, slider })`, `beforeChange({ outgoing, incoming, direction })` and `afterChange({ slide, direction })`, with `direction` being `forward` or `backward`. The plugin also has `onDragStart`, `onDragEnd`, `onResize` and `beforeDestroy`

Key	Goes to	What it does
`slides`	`preloadWebGL`	Image paths, one per slide in DOM order. From `data-webgl-src`
`displacement`	`preloadWebGL`	Path of the displacement map, or `null`. From `data-webgl-displacement`
`effect`	`webgl`	`displacement`, `rgb-shift`, `radial` or `custom`. Required
`frag`	`webgl`	GLSL fragment shader source. Required with `custom`, passed only when set
`duration`	`webgl`	Transition length in ms. The plugin defaults to `900`; passed only when set
`onIndexChanged`	the slider	Bound to the `indexChanged` event after init, with `{ displayIndex }` among its data. `configWebGL` uses it for the caption

SliderKit example

How it works

The markup

The handler

What the framework does for you

Basic

Responsive and freeze

Auto Dealers

Repair Shops

Car Rentals

Towing

Body Shops

Parking

Auto Dealers

Repair Shops

Car Rentals

Body Shops

Auto Dealers

Repair Shops

Custom arrows

Auto Dealers

Repair Shops

Car Rentals

Body Shops

Text

Slide one

Slide two

Slide three

WebGL

Iceland Church

Options reference

Attributes (HTML)

Slider options (@andresclua/sliderkit)

Plugins (@andresclua/sliderkit-plugins)

webglConfig (SliderKit.js)

`webglConfig` (SliderKit.js)