{"id":12110,"library":"swiper","title":"Swiper Slider","description":"Swiper is a highly performant, free, and open-source mobile touch slider designed for modern web and hybrid applications. It leverages hardware-accelerated transitions to provide a smooth, native-like user experience. The library is specifically focused on modern platforms and touch devices, thus it is not universally compatible with all browsers or older environments. Swiper is currently at version 12.1.3, indicating active and continuous development with frequent patch and minor releases addressing bugs and introducing new features. Its key differentiators include its focus on touch interactions, modular architecture allowing developers to include only necessary components, and a robust API for extensive customization. It integrates well with various JavaScript frameworks.","status":"active","version":"12.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/nolimits4web/Swiper","tags":["javascript","swiper","swipe","slider","touch","ios","mobile","cordova","phonegap","typescript"],"install":[{"cmd":"npm install swiper","lang":"bash","label":"npm"},{"cmd":"yarn add swiper","lang":"bash","label":"yarn"},{"cmd":"pnpm add swiper","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Swiper is a named export. ESM import is standard; CommonJS `require` might lead to issues if not transpiled or configured correctly. Avoid default import.","wrong":"const Swiper = require('swiper');\nimport Swiper from 'swiper';","symbol":"Swiper (core class)","correct":"import { Swiper } from 'swiper';"},{"note":"Modules must be imported from `swiper/modules` and then explicitly registered with the `Swiper.use()` method.","wrong":"import { Navigation, Pagination } from 'swiper';\nimport 'swiper/navigation'; // Only imports styles, not the module itself","symbol":"Swiper modules (e.g., Navigation, Pagination)","correct":"import { Navigation, Pagination } from 'swiper/modules';"},{"note":"Base Swiper CSS and module-specific CSS (like navigation, pagination) need to be imported separately. Paths changed in v7+.","wrong":"import 'swiper/swiper.min.css'; // Deprecated path\n// CSS not imported at all","symbol":"Swiper CSS","correct":"import 'swiper/css';\nimport 'swiper/css/navigation';\nimport 'swiper/css/pagination';"}],"quickstart":{"code":"import { Swiper, Navigation, Pagination, Autoplay } from 'swiper/modules';\nimport 'swiper/css';\nimport 'swiper/css/navigation';\nimport 'swiper/css/pagination';\nimport 'swiper/css/autoplay';\n\n// Initialize Swiper with custom options\ndocument.addEventListener('DOMContentLoaded', () => {\n  const swiper = new Swiper('.my-swiper-container', {\n    modules: [Navigation, Pagination, Autoplay],\n    slidesPerView: 1,\n    spaceBetween: 30,\n    loop: true,\n    autoplay: {\n      delay: 3000,\n      disableOnInteraction: false,\n    },\n    pagination: {\n      el: '.swiper-pagination',\n      clickable: true,\n    },\n    navigation: {\n      nextEl: '.swiper-button-next',\n      prevEl: '.swiper-button-prev',\n    },\n    on: {\n      init: function () {\n        console.log('Swiper initialized');\n      },\n    },\n  });\n\n  // Example of using Swiper instance methods\n  document.querySelector('.go-next')?.addEventListener('click', () => {\n    swiper.slideNext();\n  });\n});\n\n// Minimal HTML structure (add this to your HTML file)\n/*\n<div class=\"my-swiper-container swiper\">\n  <div class=\"swiper-wrapper\">\n    <div class=\"swiper-slide\">Slide 1</div>\n    <div class=\"swiper-slide\">Slide 2</div>\n    <div class=\"swiper-slide\">Slide 3</div>\n  </div>\n  <div class=\"swiper-pagination\"></div>\n  <div class=\"swiper-button-prev\"></div>\n  <div class=\"swiper-button-next\"></div>\n</div>\n<button class=\"go-next\">Go to next slide (programmatic)</button>\n*/","lang":"typescript","description":"Demonstrates importing Swiper and its modules (Navigation, Pagination, Autoplay), importing necessary CSS, and initializing a basic Swiper instance with common features like loop, autoplay, navigation, and pagination."},"warnings":[{"fix":"Ensure all required modules are imported from `swiper/modules` and passed to `Swiper.use([Module1, Module2])` before initializing Swiper. Update CSS import paths (e.g., `swiper/css`, `swiper/css/navigation`).","message":"Swiper versions 7 and above introduced significant breaking changes, particularly regarding the modular structure and CSS import paths. Modules (like Navigation, Pagination) are no longer automatically included and must be explicitly imported and registered using `Swiper.use()`.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Review Swiper's compatibility documentation if targeting specific legacy browsers or non-standard environments. Consider polyfills or alternative libraries if broad legacy support is critical.","message":"Swiper is designed for modern touch devices and web environments. It explicitly states it is not compatible with all platforms, which may lead to unexpected behavior or lack of functionality in older browsers or non-touch environments.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Thoroughly test existing Swiper implementations after upgrading to a new major version. Consult the official migration guide for specific details on breaking changes and updated configuration options related to slide positioning and looping.","message":"Major versions, like v12.0.0, often introduce breaking changes, even if not explicitly detailed in the minor changelog. For v12, fixes related to `slidesOffsetBefore`, `slidesOffsetAfter`, `centeredSlides`, `slidesPerView`, and `loop` might indicate changes in how these options interact or are configured, potentially affecting existing layouts.","severity":"breaking","affected_versions":">=12.0.0"},{"fix":"Utilize framework-specific Swiper components when available. If using vanilla Swiper, ensure proper initialization and destruction within the framework's component lifecycle methods (e.g., `useEffect` for React, `onMounted` and `onUnmounted` for Vue).","message":"If using Swiper with a JavaScript framework (e.g., React, Vue, Angular), dedicated wrapper components (like `swiper/react`) are often available and recommended. Using the vanilla Swiper API directly within framework lifecycles without proper cleanup can lead to memory leaks or unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import { Swiper } from 'swiper';` for ESM and that your build tools correctly handle module resolution. If using CommonJS, verify your bundler's configuration or consider using an older Swiper version with explicit CJS support.","cause":"Attempting to use `Swiper` as a default import or `require` when it's a named export, or incorrect build configuration.","error":"TypeError: Swiper is not a constructor"},{"fix":"Import all necessary modules from `swiper/modules` and pass them in an array to the `modules` option during Swiper initialization: `new Swiper('.swiper', { modules: [Navigation, Pagination] });`.","cause":"Swiper modules (like Navigation, Pagination, Autoplay) are not explicitly imported and registered with the Swiper instance.","error":"TypeError: Cannot read properties of undefined (reading 'init') OR TypeError: this.params.navigation is undefined"},{"fix":"Verify that `import 'swiper/css';` and `import 'swiper/css/navigation';` (and other specific module CSS) are included in your entry file. Also, ensure your HTML contains the correct elements (e.g., `<div class=\"swiper-button-next\"></div>`) within or adjacent to the Swiper container, as specified by Swiper's documentation.","cause":"The corresponding CSS for Swiper modules (e.g., `swiper/css/navigation`, `swiper/css/pagination`) is not imported, or the HTML structure for the navigation/pagination elements is incorrect.","error":"Swiper navigation arrows/pagination dots/scrollbar are not visible or styled correctly."}],"ecosystem":"npm"}