Multislider

About

Multislider shows more than one slide at a time. How many is up to your CSS. A slide with width: 20% means five visible slides, and a media query at a smaller breakpoint can drop that to two. The library never sets slide widths and has no slidesVisible option.

It is TypeScript, has zero runtime dependencies, and ships as ESM plus one IIFE build for script tag users. It runs in every evergreen browser; exact versions are under browser support. Slides never get cloned or reordered to fake a loop, so your DOM stays the shape you wrote it, with one exception noted under markup.

Markup

Four parts, three of which you have to supply.

<div id="mySlider">
  <div class="MS-content">              <!-- viewport -->
    <div class="item">Slide 1</div>    <!-- slides -->
    <div class="item">Slide 2</div>
    <div class="item">Slide 3</div>
  </div>
  <button type="button" data-ms="prev">Prev</button>
  <button type="button" data-ms="next">Next</button>
</div>

At init the library creates a div.ms-track inside the viewport and moves the slides into it exactly once. destroy() puts the original DOM back.

Critical styles are set inline, so there is no stylesheet to import. The viewport gets overflow: hidden. The track gets display: flex, width: 100%, and will-change: transform. Slides get flex: 0 0 auto. Percentage widths resolve against the track, whose width matches the viewport content box, which is why v1 era CSS keeps working.

An endless loop needs enough content to cover the viewport plus the widest slide. If your slides do not add up to that, the library duplicates the whole set as many times as the viewport needs, marks the copies aria-hidden="true" and inert, and carries on. Three logos on an ultrawide monitor might clone six sets; the clone count is capped by the maxClones option (default 600). Past that cap looping turns off, the copies are removed, the slider clamps at the ends with autoplay rewinding to the start, and a warning goes to the console. This is the only case where anything gets cloned.

CSS

Slide count is a width percentage. Divide 100 by the number of slides you want to see.

.item { width: 50%; }      /* 2 slides */
.item { width: 33.3333%; } /* 3 slides */
.item { width: 25%; }      /* 4 slides */
.item { width: 20%; }      /* 5 slides */

Change the count per breakpoint with media queries.

#mySlider .item {
  width: 20%;
}

@media (max-width: 1200px) { #mySlider .item { width: 25%; } }
@media (max-width: 992px)  { #mySlider .item { width: 33.3333%; } }
@media (max-width: 768px)  { #mySlider .item { width: 50%; } }

After a breakpoint change the slider re-measures through a ResizeObserver and keeps the same slide leading, so nothing jumps.

Padding, borders, and margins on a slide count toward its size, and so does gap on the track, so spacing works however you like to write it.

#mySlider .ms-track { gap: 16px; }  /* or margins on .item, both work */

One caveat: changing only a gap or a margin at a breakpoint does not resize the track, so the ResizeObserver cannot see it. Call refresh() after such a change. Changing slide widths remeasures automatically. Also avoid order, flex-direction: row-reverse, and transitions on transform for slides or the track: the wrap math assumes DOM order is layout order and that transforms apply instantly. Prefer margins over horizontal padding on the viewport, since slides wrap at the content box edge and padding would show them popping in and out. Everything else, including the arrow buttons, is yours to style.

Usage

ESM

import { Multislider } from '@tjblackman/multislider';

const slider = new Multislider('#mySlider', {
  interval: 3000,
  duration: 600,
});

Script tag

The IIFE build puts the class on window.Multislider. Bare unpkg and jsdelivr URLs serve it directly.

<script src="https://unpkg.com/@tjblackman/multislider"></script>
<script>
  new Multislider('#mySlider', { mode: 'marquee', speed: 40 });
</script>

Bundler users who want the same global build can import '@tjblackman/multislider/global', which also types window.Multislider for TypeScript.

The constructor takes a selector string or an element. It throws if the target or its viewport cannot be found, or if that element is already a slider. Many independent instances on one page are fine.

Options

Every option is optional. Defaults are below.

Methods

Prev and next buttons call prev() / next() when advanceBy is "one", and prevPage() / nextPage() when it is "page".

Pausing is a set of reasons, not a boolean. Hover, keyboard focus, an off screen tab, a matched pauseAbove query, a drag, reduced motion, and pause() each add their own reason ("hover", "focus", "hidden", "media", "drag", "reduced-motion", "api"). Autoplay runs only when the set is empty, which is why hovering a slider you already paused through the API does not accidentally resume it.

Events

Native CustomEvents, dispatched on the root element, bubbling.

const el = document.querySelector('#mySlider');

el.addEventListener('multislider:afterchange', (e) => {
  console.log(e.detail.from, '->', e.detail.to);
});

el.addEventListener('multislider:beforechange', (e) => {
  if (someCondition) e.preventDefault();
});

Accessibility

• The root gets role="region" and aria-roledescription="carousel". It also gets aria-label="slideshow", but only if you did not label it yourself.
• Buttons with no accessible name get aria-label="Previous slide" or "Next slide". Give them your own label and the library leaves it alone.
• Autoplay pauses on focusin anywhere inside the root and resumes on focusout, under its own "focus" reason. It applies even with hoverPause: false, so a stray mouse movement can never resume a slider a keyboard user is reading.
• Slides get role="group", aria-roledescription="slide", and a positional label like "2 of 5" unless you labelled them yourself. The track carries aria-live: "off" while auto-rotating, "polite" while paused or when autoplay is disabled.
• Tabbing to a link or button in a partly hidden slide jumps the track, with no tween, so the focused slide is fully on screen.
• ArrowLeft and ArrowRight step the slider when focus is on the root or on one of the buttons. The arrow points at the edge new content enters from, so RTL flips the mapping, and presses with a modifier key held are left to the browser. The root only receives arrow keys if you give it a tabindex; the buttons work out of the box.
• prefers-reduced-motion: reduce sets step duration to 0, disables autoplay, and holds the marquee still. Set respectReducedMotion: false to opt out, though think hard before you do.

Browser support

The build targets ES2022, and the limiting syntax feature is private class methods. That sets the floor:

"Full behavior" is the inert attribute on cloned slides; older browsers ignore it, and a cloned slide's links could take keyboard focus despite being aria-hidden. Everything else degrades gracefully: without ResizeObserver you call refresh() after layout changes, and without MediaQueryList.addEventListener the pause breakpoints evaluate once at init.

The CSS bar is far lower than the JS bar: the page needs flexbox and 2D transforms (Safari 9 era), and the library sets everything it needs inline. The newest CSS it uses is touch-action: pan-y (Safari 13) so touch dragging and vertical page scrolling coexist. Any browser that can parse the JS clears all of it.

Migrating from v1

v1 was a jQuery plugin. v2 is a class. The markup you already have keeps working, since the old .MS-content, .MS-left, and .MS-right hooks are still recognized. The v1 source lives on the v1 branch and the v1.0.0 tag.