Universal Swipe.js (swipe-js-iso)

2.1.5 · maintenance · verified Wed Apr 22

swipe-js-iso is a lightweight, dependency-free JavaScript library for creating touch-enabled carousels and sliders, specifically forked from the original Swipe.js project. It aims to be compatible with 'universal' (isomorphic) applications, meaning it can theoretically be used in both browser and server-side rendering contexts (though typically client-side focused for DOM manipulation). The current stable version is 2.1.5, with the last publish being 7 years ago, suggesting a maintenance or inactive release cadence rather than active development. Its key differentiators include its minimal footprint and lack of external dependencies, providing a simple, performant solution for basic image or content swiping, particularly when alternatives like Swiper.js might be considered too heavy or feature-rich.

Common errors

```
Uncaught TypeError: Cannot read properties of null (reading 'style')
```
cause The HTML element passed to `Swipe()` was not found in the DOM, meaning `document.getElementById('slider')` returned `null`.

fix Ensure the DOM element exists and the script is executed after the element is available (e.g., at the end of `<body>` or inside `DOMContentLoaded` event listener). Verify the ID (`'slider'`) matches the HTML element's ID.
```
Swipe is not defined
```
cause The `Swipe` function was not imported or made available in the current scope. This typically happens if using ESM `import` in a CJS environment, incorrect named/default import, or if the script is loaded incorrectly.

fix For ESM, use `import Swipe from 'swipe-js-iso';`. For CommonJS, use `const Swipe = require('swipe-js-iso');`. For global script tags, ensure the `swipe-js-iso` script is loaded before your custom script attempts to use `Swipe`.
```
Slider not visible or slides stacked vertically
```
cause Missing or incorrect CSS styles, particularly those related to `overflow`, `visibility`, `position`, `float`, and `width` for `.swipe`, `.swipe-wrap`, and `.swipe-wrap > div`.

fix Copy the essential CSS styles provided in the `README` exactly into your stylesheet. Use browser developer tools to inspect the elements and verify that the styles are correctly applied and not being overridden.

Warnings

gotcha This library is a fork of the original Swipe.js. While it aims for 'universal' compatibility and is published to NPM, its last update was 7 years ago. This suggests it may not receive active development, bug fixes, or security updates, and might lag behind modern browser APIs or alternative slider libraries in features and performance.
Fix: For actively maintained and feature-rich sliders, consider alternatives like Swiper.js, which is under active development. If `swipe-js-iso` meets minimal needs, thoroughly test its compatibility and performance in your target environments.
breaking The library relies on specific HTML structure and CSS for proper functioning, including `div.swipe > div.swipe-wrap > div`. Deviations from this structure or missing/incorrect CSS (e.g., `overflow: hidden`, `position: relative`, `float: left`) will likely prevent the slider from working or displaying correctly.
Fix: Always ensure the exact HTML markup (`<div class="swipe"><div class="swipe-wrap"><div></div></div></div>`) and the provided essential CSS rules are applied. Inspect the DOM and computed styles for debugging layout issues.
gotcha As a client-side UI component heavily relying on DOM manipulation, `swipe-js-iso` is not designed to run directly in a Node.js server-side rendering (SSR) environment without a browser-like DOM implementation (e.g., JSDOM). Attempting to instantiate `Swipe` on `document.getElementById` will fail if `document` is not defined.
Fix: When using in universal/isomorphic applications, ensure `Swipe` initialization is guarded by a check for a browser environment (e.g., `if (typeof window !== 'undefined')`) or use a library like JSDOM for server-side DOM emulation if strict SSR is required.
gotcha The `continuous` option (defaulting to `true`) can behave unexpectedly with a very small number of slides, as the library duplicates slides to create the continuous effect. If there are not enough unique slides to fill the view, the 'loop' might appear broken or glitchy.
Fix: Ensure you have a sufficient number of slides (typically at least three, more if `widthOfSiblingSlidePreview` is used) for the `continuous` option to work effectively. For a finite set of slides where continuity is not needed, set `continuous: false`.

Install

npm install swipe-js-iso npm
yarn add swipe-js-iso yarn
pnpm add swipe-js-iso pnpm

Imports

Swipe
wrong:
```
import { Swipe } from 'swipe-js-iso';
```
correct:
```
import Swipe from 'swipe-js-iso';
```
The library appears to use a default export for the main Swipe function, or exposes it globally if included via script tag. The README example `const mySwipe = Swipe(...)` suggests a default export in module environments, or direct access in global scope.
Swipe (with new keyword)
wrong:
```
const mySwipe = Swipe(document.getElementById('slider'), { /* options */ });
```
correct:
```
const mySwipe = new Swipe(document.getElementById('slider'), { /* options */ });
```
While the quickstart shows `Swipe(...)` without `new`, the 'Example' section explicitly uses `new Swipe(...)`. Both forms are shown in the README, implying `new` is optional or preferred for constructor-like usage.
CommonJS require
wrong:
```
const { Swipe } = require('swipe-js-iso');
```
correct:
```
const Swipe = require('swipe-js-iso');
```
For CommonJS environments, `require('swipe-js-iso')` will likely return the main Swipe function. Assuming it bundles for CJS, it would typically expose the function directly.

Quickstart

This quickstart demonstrates how to set up a basic swipeable carousel using `swipe-js-iso` with HTML, CSS, and JavaScript. It initializes the slider, configures common options like auto-play and transition speed, and exposes API methods (`prev`, `next`) for external controls.

<!-- index.html -->
<style>
  .swipe {
    overflow: hidden;
    visibility: hidden;
    position: relative;
  }
  .swipe-wrap {
    overflow: hidden;
    position: relative;
  }
  .swipe-wrap > div {
    float: left;
    width: 100%;
    position: relative;
  }
</style>

<div id="slider" class="swipe">
  <div class="swipe-wrap">
    <div><h2>Slide 1</h2><p>Content for slide 1</p></div>
    <div><h2>Slide 2</h2><p>Content for slide 2</p></div>
    <div><h2>Slide 3</h2><p>Content for slide 3</p></div>
  </div>
</div>

<button onclick="mySwipe.prev()">Prev</button>
<button onclick="mySwipe.next()">Next</button>

<script type="module">
  import Swipe from 'swipe-js-iso';

  document.addEventListener('DOMContentLoaded', () => {
    const mySwipe = new Swipe(document.getElementById('slider'), {
      startSlide: 0,
      speed: 400,
      auto: 3000,
      continuous: true,
      disableScroll: false,
      stopPropagation: false,
      callback: function(index, elem) {
        console.log('Slide changed to:', index, elem);
      },
      transitionEnd: function(index, elem) {
        console.log('Transition ended for:', index, elem);
      }
    });

    // Expose for global buttons
    window.mySwipe = mySwipe;

    console.log('Total slides:', mySwipe.getNumSlides());
    console.log('Current slide position:', mySwipe.getPos());
  });
</script>

view raw JSON →