DOCSEARCHbyAlgolia
Submit Docs

Swiper

repository·master·Indexed 13 days ago

https://github.com/nolimits4web/swiper

A modern, hardware-accelerated mobile touch slider and framework for high-performance web and hybrid applications. Swiper is library-agnostic, tree-shakeable, and supports advanced features including virtual slides, RTL, and various 3D transition effects. Version 14.1.0 targets evergreen browsers and provides native SSR support and a module augmentation pattern for TypeScript type safety.

Tokens
15.9K
Snippets
31
Records
59
Agent score
97%

What's inside Swiper

  1. Overview of Swiper features

    master

    Swiper is a modern, mobile-friendly touch slider designed for mobile websites, web apps, and hybrid apps. It features hardware-accelerated transitions and native-like behavior.

    Key capabilities include:

    • Tree-shakeable: Import only the modules you need to keep bundles small.
    • Library Agnostic: Works without dependencies like jQuery, but is compatible with them.
    • Rich UI & Effects: Built-in support for Pagination, Navigation arrows, Scrollbars, Parallax, and transition effects like Fade, Flip, 3D Cube, and 3D Coverflow.
    • Advanced Layouts: Supports RTL (Right-to-Left), Multi-row slides, Flexbox layouts, and highly configurable grids (slides per view, per column, etc.).
    • Performance Optimizations: Includes Image Lazy Loading and Virtual Slides (to manage large amounts of content by keeping only necessary slides in the DOM).
    • Control Modes: Supports Loop mode, Autoplay, Keyboard/Mousewheel control, Nested sliders, and Two-way control (one Swiper controlling another).

  2. Introduction to Swiper

    master

    Swiper is a modern, free mobile touch slider designed for mobile websites, mobile web apps, and mobile native/hybrid apps. It features hardware-accelerated transitions and provides native-like touch behavior.

    Note on Compatibility: Swiper is optimized for modern platforms and apps to ensure high performance and simplicity; it is not intended to support legacy platforms.

  3. Deprecation of Swiper.use([...])

    master

    The static method Swiper.use([...]), which was previously used to globally register modules, is being reconsidered for deprecation. Modern usage patterns favor passing the modules array directly into the Swiper constructor.

    In upcoming versions (v15), using Swiper.use() may trigger a console warning, and it is planned for removal in v16. It is recommended to switch to the constructor-based module registration to ensure future compatibility.

  4. SSR (Server-Side Rendering) compatibility in Swiper v14

    master

    Swiper v14 is designed to be safe for SSR environments. The library has removed the ssr-window dependency in favor of native environment guards (e.g., typeof document !== 'undefined').

    To ensure compatibility in your SSR setup (such as React renderToString or Vue SSR), Swiper ensures that:

    • Imports and new Swiper() instances do not throw errors in pure Node.js environments.
    • Web component register() calls are safe.
    • No unguarded references to document or HTMLElement are accessed during the initial execution in a non-browser environment.

  5. SSR (Server-Side Rendering) support in Swiper v14

    master

    In Swiper v14, the ssr-window package has been removed. SSR support is now handled via inline typeof guards within the core logic (specifically in the constructor and mount() method in core.ts) and lazy DOM creation in virtual.ts.

    Behavioral Notes:

    • Pure Node.js environments: Instantiating new Swiper(...) in a pure Node environment will no longer throw errors on unguarded document or HTMLElement globals. It is designed to be a silent no-op, maintaining parity with v12 behavior.
    • Framework SSR (Next.js, React, Vue): Framework wrappers are not affected by these changes because they are designed to instantiate Swiper only within client-side mount effects (e.g., useEffect in React or onMounted in Vue).

  6. Breaking-change policy for Swiper v14

    master

    Swiper v14 follows a strict zero runtime breaking changes policy. When upgrading to v14, you can expect the following to remain identical to previous versions:

    • Options: All option names, default values, and shapes.
    • Events: All event names, payloads, and timing.
    • Methods: All public method signatures.
    • Module Imports: Imports from paths like swiper/modules or swiper/react will resolve identically.

    Note on Types: While runtime behavior is preserved, type-level breaking changes may occur. If you were using any to access internal properties, you may encounter new TypeScript errors. These changes are intended to be minimized and should be documented in the migration guide.

  7. How Swiper v14 module augmentation works

    master

    Swiper v14 uses a module augmentation pattern to provide type safety for its modular architecture. Instead of a single monolithic type, each module (e.g., Navigation, Pagination) provides its own *Options, *Methods, and *Events interfaces.

    To ensure these types are correctly applied to the main Swiper instance, modules use a declare module '../../core/core' block. This allows the SwiperOptions interface in the core to be augmented with module-specific properties.

    Usage Pattern: When using modules, you must import them from swiper/modules to trigger these side-effect augmentations. This ensures that when you instantiate new Swiper(el, { ... }), your IDE provides autocomplete for the specific options provided by the imported modules.

    // Importing from 'swiper/modules' triggers the type augmentation
import { Navigation, Pagination } from 'swiper/modules';
import Swiper from 'swiper';

const swiper = new Swiper('.swiper', {
  // Autocomplete will work for navigation and pagination options here
  navigation: {
    nextEl: '.swiper-button-next',
    prevEl: '.swiper-button-prev',
  },
  pagination: { type: 'bullets' },
});

  8. The Swiper Type Structure

    master

    In Swiper v14, Swiper is defined as both an interface and a class. This dual definition is critical for the module augmentation pattern:

    1. The interface Swiper acts as the type definition that modules can augment with new properties and methods.
    2. The class Swiper provides the actual runtime implementation.

    This separation allows modules to merge their specific functionality (like navigation or pagination) into the Swiper interface without causing type collisions with the main class declaration.

    export interface Swiper {
  /* properties + method signatures */
}
export class Swiper {
  /* runtime — implements the interface */
}

  9. SSR (Server-Side Rendering) behavior in Swiper

    master

    Swiper v14 is designed to handle Server-Side Rendering (SSR) environments gracefully.

    • Framework Wrappers (React/Vue): The official React and Vue wrappers are SSR-safe because they only call new Swiper() inside lifecycle effects (like useEffect or onMounted), which do not execute on the server.
    • Imperative Instantiation: If you manually call new Swiper() in a pure Node.js environment, Swiper now uses typeof guards to prevent errors when accessing document or HTMLElement. In these cases, the constructor will gracefully no-op rather than throwing a runtime error.
    • Web Components: The register() method for Swiper Custom Elements is a no-op in SSR environments.

  10. How module augmentation works in Swiper v14

    master

    Swiper v14 uses declaration merging (rather than generics like Swiper<TModules>) to handle module types. This approach ensures better developer experience at call sites and follows ecosystem conventions.

    When using modules, the types for Swiper, SwiperOptions, and SwiperEvents are augmented via declaration merging. This allows the core Swiper instance to recognize the specific options, events, and methods provided by the modules you have loaded.

    Key distinction for imports:

    • swiper/core: Stays "bare" and does not automatically register modules. It mirrors the main entry's semantics.
    • swiper/bundle: Includes dedicated augmentation-loading types (dist/swiper-bundle.d.ts). Because the bundle auto-registers every module at runtime, its types are designed to expose all module options, events, and methods without requiring an explicit import 'swiper/modules'.

  11. Understanding Swiper v15 Core Decomposition

    master

    Swiper v15 is transitioning from a prototype-mixin architecture to a composition-based architecture.

    Current Architecture (v14): Every Swiper instance automatically includes all prototype methods (e.g., translate, loop, grabCursor, breakpoints) via Object.assign(Swiper.prototype, prototypes). This ensures all methods are available but prevents bundlers from tree-shaking unused features, resulting in a larger baseline bundle size.

    Target Architecture (v15): The goal is to make the core tree-shakeable. The Swiper class will expose a minimal set of public methods, while the underlying logic is moved to pure functions that take a Swiper instance as an argument (e.g., slideNext(swiper, ...)).

    Key takeaway for developers: While the internal implementation is changing to improve maintainability and tree-shaking, the public API surface (e.g., swiper.slideNext(), swiper.update()) is intended to remain identical to ensure zero breakage for existing codebases.

  12. Getting Started with Swiper

    master

    To begin using Swiper in your project, you can access the official documentation for setup, API references, and interactive examples via the following links:

    • Getting Started Guide: Comprehensive instructions for installation and initial configuration.
    • API Reference: Detailed documentation of all Swiper methods, properties, events, and classes.
    • Demos: A collection of interactive examples showing various Swiper configurations and features.
    https://swiperjs.com/get-started/
https://swiperjs.com/swiper-api/
https://swiperjs.com/demos/