swiper

library12.1.3jsnpmunverified

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.

web-framework communication

npm install swiper

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SWIPER

swiper

web-frameworkjavascriptv12.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Swiper (core class)

✓ import { Swiper } from 'swiper';

✗ const Swiper = require('swiper'); import Swiper from 'swiper';

Swiper is a named export. ESM import is standard; CommonJS `require` might lead to issues if not transpiled or configured correctly. Avoid default import.

Swiper modules (e.g., Navigation, Pagination)

✓ import { Navigation, Pagination } from 'swiper/modules';

✗ import { Navigation, Pagination } from 'swiper'; import 'swiper/navigation'; // Only imports styles, not the module itself

Modules must be imported from `swiper/modules` and then explicitly registered with the `Swiper.use()` method.

Swiper CSS

✓ import 'swiper/css'; import 'swiper/css/navigation'; import 'swiper/css/pagination';

✗ import 'swiper/swiper.min.css'; // Deprecated path // CSS not imported at all

Base Swiper CSS and module-specific CSS (like navigation, pagination) need to be imported separately. Paths changed in v7+.

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.

import { Swiper, Navigation, Pagination, Autoplay } from 'swiper/modules'; import 'swiper/css'; import 'swiper/css/navigation'; import 'swiper/css/pagination'; import 'swiper/css/autoplay'; // Initialize Swiper with custom options document.addEventListener('DOMContentLoaded', () => { const swiper = new Swiper('.my-swiper-container', { modules: [Navigation, Pagination, Autoplay], slidesPerView: 1, spaceBetween: 30, loop: true, autoplay: { delay: 3000, disableOnInteraction: false, }, pagination: { el: '.swiper-pagination', clickable: true, }, navigation: { nextEl: '.swiper-button-next', prevEl: '.swiper-button-prev', }, on: { init: function () { console.log('Swiper initialized'); }, }, }); // Example of using Swiper instance methods document.querySelector('.go-next')?.addEventListener('click', () => { swiper.slideNext(); }); }); // Minimal HTML structure (add this to your HTML file) /* <div class="my-swiper-container swiper"> <div class="swiper-wrapper"> <div class="swiper-slide">Slide 1</div> <div class="swiper-slide">Slide 2</div> <div class="swiper-slide">Slide 3</div> </div> <div class="swiper-pagination"></div> <div class="swiper-button-prev"></div> <div class="swiper-button-next"></div> </div> <button class="go-next">Go to next slide (programmatic)</button> */

Debug

Known issues

breakingSwiper 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()`.

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`).

affects: >=7.0.0

gotchaSwiper 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.

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.

affects: >=1.0.0

breakingMajor 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.

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.

affects: >=12.0.0

gotchaIf 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.

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).

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Swiper is not a constructor

Attempting to use `Swiper` as a default import or `require` when it's a named export, or incorrect build configuration.

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.

TypeError: Cannot read properties of undefined (reading 'init') OR TypeError: this.params.navigation is undefined

Swiper modules (like Navigation, Pagination, Autoplay) are not explicitly imported and registered with the Swiper instance.

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] });`.

Swiper navigation arrows/pagination dots/scrollbar are not visible or styled correctly.

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.

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.

Upgrade

Version history

12.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

35 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/nolimits4web/Swiper ↗

packagehttps://www.npmjs.com/package/swiper ↗

homepagehttps://swiperjs.com ↗