Swiper Slider

Common errors

• TypeError: Swiper is not a constructor

  cause 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

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

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

Warnings

• breaking 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()`.
  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`).
• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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).

Install

• npm install swiper npm
• yarn add swiper yarn
• pnpm add swiper pnpm

Imports

• Swiper (core class)
  wrong:

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

  correct:

  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)
  wrong:

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

  correct:

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

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

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

  correct:

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

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

Quickstart

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>
*/