{"id":17378,"library":"swipe-js-iso","title":"Universal Swipe.js (swipe-js-iso)","description":"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.","status":"maintenance","version":"2.1.5","language":"javascript","source_language":"en","source_url":"https://github.com/voronianski/swipe-js-iso","tags":["javascript"],"install":[{"cmd":"npm install swipe-js-iso","lang":"bash","label":"npm"},{"cmd":"yarn add swipe-js-iso","lang":"bash","label":"yarn"},{"cmd":"pnpm add swipe-js-iso","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { Swipe } from 'swipe-js-iso';","symbol":"Swipe","correct":"import Swipe from 'swipe-js-iso';"},{"note":"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.","wrong":"const mySwipe = Swipe(document.getElementById('slider'), { /* options */ });","symbol":"Swipe (with new keyword)","correct":"const mySwipe = new Swipe(document.getElementById('slider'), { /* options */ });"},{"note":"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.","wrong":"const { Swipe } = require('swipe-js-iso');","symbol":"CommonJS require","correct":"const Swipe = require('swipe-js-iso');"}],"quickstart":{"code":"<!-- index.html -->\n<style>\n  .swipe {\n    overflow: hidden;\n    visibility: hidden;\n    position: relative;\n  }\n  .swipe-wrap {\n    overflow: hidden;\n    position: relative;\n  }\n  .swipe-wrap > div {\n    float: left;\n    width: 100%;\n    position: relative;\n  }\n</style>\n\n<div id=\"slider\" class=\"swipe\">\n  <div class=\"swipe-wrap\">\n    <div><h2>Slide 1</h2><p>Content for slide 1</p></div>\n    <div><h2>Slide 2</h2><p>Content for slide 2</p></div>\n    <div><h2>Slide 3</h2><p>Content for slide 3</p></div>\n  </div>\n</div>\n\n<button onclick=\"mySwipe.prev()\">Prev</button>\n<button onclick=\"mySwipe.next()\">Next</button>\n\n<script type=\"module\">\n  import Swipe from 'swipe-js-iso';\n\n  document.addEventListener('DOMContentLoaded', () => {\n    const mySwipe = new Swipe(document.getElementById('slider'), {\n      startSlide: 0,\n      speed: 400,\n      auto: 3000,\n      continuous: true,\n      disableScroll: false,\n      stopPropagation: false,\n      callback: function(index, elem) {\n        console.log('Slide changed to:', index, elem);\n      },\n      transitionEnd: function(index, elem) {\n        console.log('Transition ended for:', index, elem);\n      }\n    });\n\n    // Expose for global buttons\n    window.mySwipe = mySwipe;\n\n    console.log('Total slides:', mySwipe.getNumSlides());\n    console.log('Current slide position:', mySwipe.getPos());\n  });\n</script>","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"<=2.1.6"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The HTML element passed to `Swipe()` was not found in the DOM, meaning `document.getElementById('slider')` returned `null`.","error":"Uncaught TypeError: Cannot read properties of null (reading 'style')"},{"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`.","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.","error":"Swipe is not defined"},{"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.","cause":"Missing or incorrect CSS styles, particularly those related to `overflow`, `visibility`, `position`, `float`, and `width` for `.swipe`, `.swipe-wrap`, and `.swipe-wrap > div`.","error":"Slider not visible or slides stacked vertically"}],"ecosystem":"npm","meta_description":null}