Swiper Admin & Architecture Guide

This guide is the technical reference for engineers, architects, and maintainers who integrate, extend, audit, or build on Swiper. It documents the library's architecture, its complete public API (every parameter, method, property, and event), the build and packaging system, its styling and CSS-class contract, security posture, and a roadmap of known issues and improvements.

It is the companion to the User Guide (everyday usage and recipes). Where the User Guide shows how to use Swiper, this guide explains how Swiper is built and gives the exhaustive reference tables.

Note

Reference target: Swiper v12.2.0 (package name swiper), MIT-licensed, authored by Vladimir Kharlampidi. Homepage: swiperjs.com. This document is derived directly from the TypeScript definitions and source.

1. Executive Summary

Swiper is a dependency-free, framework-agnostic touch slider for the web. Its defining engineering characteristics:

• Modular & tree-shakeable. A small core handles layout, touch, and transitions; every feature (navigation, pagination, autoplay, effects, zoom, …) is an independently importable module. Unused modules never enter your bundle.
• Multi-target distribution. One source produces six consumption surfaces: a core ES module, an all-in-one bundle, a React component set, a Vue component set, a Web Component (<swiper-container>), and per-module CSS.
• No runtime dependencies. Swiper ships zero production dependencies. There is no server, no network I/O, no configuration files, and no secrets — it is a client-side UI library configured entirely by a JavaScript options object.
• Type-first API. The authoritative API contract lives in TypeScript declaration files (.d.ts) whose JSDoc carries the description, type, default, and examples for every option, method, and event.

2. Architecture

2.1 High-level structure

                         ┌─────────────────────────────┐
                         │        Swiper core           │
                         │  (src/core/*)                │
                         │  layout · touch · transition │
                         │  translate · update · loop   │
                         └───────────────┬──────────────┘
                                         │ lifecycle events + extendParams()
        ┌────────────────────────────────┼────────────────────────────────┐
        │                                 │                                 │
 ┌──────┴───────┐                 ┌───────┴────────┐                ┌───────┴────────┐
 │  Feature      │                │   Effect        │                │  Integration   │
 │  modules      │                │   modules       │                │  wrappers      │
 │ (src/modules) │                │ (effect-*)      │                │ react/vue/     │
 │ navigation    │                │ fade/cube/flip  │                │ element        │
 │ pagination    │                │ coverflow/cards │                │                │
 │ autoplay …    │                │ creative        │                │                │
 └──────────────┘                 └────────────────┘                └────────────────┘

 dist/ build targets:
   swiper.mjs              core class
   swiper-bundle.mjs       core + all modules
   modules/index.mjs       individual modules (swiper/modules)
   swiper-react.mjs        React components
   swiper-vue.mjs          Vue components
   swiper-element.mjs      <swiper-container> web component
   *.css                   core + per-module styles

2.2 The core (src/core)

The core is responsible for everything that is not an optional feature. Its subfolders map directly to responsibilities (all scored HIGH in source triage):

2.3 The module system

A module is a function conforming to the SwiperModule type (from src/types/shared.d.ts):

export type SwiperModule = (options: {
  params: Swiper['params'];
  swiper: Swiper;
  extendParams: (obj: { [name: string]: any }) => void;
  on: Swiper['on'];
  once: Swiper['once'];
  off: Swiper['off'];
  emit: Swiper['emit'];
}) => void;

Each module receives the live instance and the event bus. It:

1. Calls extendParams() to register its own option object and defaults (e.g. the navigation module registers the navigation option block).
2. Subscribes to core lifecycle events (init, update, slideChange, setTranslate, resize, …) via on().
3. Adds its own state/methods to the instance (e.g. swiper.navigation, swiper.autoplay) and emits its own events (navigationNext, autoplayStart, …).

Modules are installed either by passing them in the modules array per-instance, or globally with the static Swiper.use([...]). The bundle build pre-installs all of them.

Note

This is why the User Guide repeatedly frames a feature as "three pieces": the module import (JS), the modules array entry (installation), and the CSS import (styling). The architecture enforces that separation to keep the core tiny.

2.4 Integration wrappers

The wrappers are thin: they translate framework idioms (props, slots, reactivity) into the same core SwiperOptions object and instance the User Guide already documented. The React/Vue components additionally manage the instance lifecycle (init on mount, update on prop change, destroy on unmount).

3. Packaging & Distribution

3.1 The exports map (canonical entry points)

The published package's exports field (src/copy/package.json) is the authoritative list of import specifiers. Engineers should treat it as the contract — only these entry points are public.

Per-module CSS entry points exist for: a11y, autoplay, controller, effect-coverflow, effect-cube, effect-fade, effect-flip, effect-creative, effect-cards, free-mode, grid, hash-navigation, history, keyboard, manipulation, mousewheel, navigation, pagination, parallax, scrollbar, thumbs, virtual, zoom — and the same set again under swiper/element/css/* for the Shadow-DOM web component.

Important

The web component uses separate *-element.css files (suffixed -element) because Shadow-DOM-scoped styling differs from light-DOM styling. When using <swiper-container>, inject styles via the element's injectStyles/injectStylesUrls properties rather than importing global CSS.

3.2 Build pipeline

The build is driven by custom Node scripts (scripts/), orchestrated through npm scripts in the root package.json:

Toolchain (from devDependencies): Rollup (rollup, @rollup/plugin-babel, @rollup/plugin-node-resolve, @rollup/plugin-replace) for JS bundling; Babel (@babel/core, preset-env, preset-react) for transpilation; PostCSS (postcss, postcss-nested, autoprefixer, cssnano) and Less (less) plus clean-css for styles; terser for minification; Vite for the playgrounds.

Note

Per the README's contribution rule, all changes go into src/ only — dist/ is generated. The dist/ folder is what consumers should use in production; src/ is the editable source of truth.

3.3 Build-time flags

The single build-time configuration value found in source is the environment variable SWIPER_BUILD_MODULES (read via process.env in scripts/utils/helper.js). It controls which modules the build script includes when assembling targets. It is a build concern only — it has no effect at runtime in the browser.

Note

Swiper has no runtime configuration files and no runtime environment variables. All runtime behavior is set through the SwiperOptions object passed to the constructor (documented in §4). There is no .env, no config schema, and no config loader to manage.

4. Complete Parameter Reference (SwiperOptions)

Every core parameter, its type, and its default — taken verbatim from src/types/swiper-options.d.ts. Module-specific option blocks are in §6.

4.1 Initialization & lifecycle

4.2 Slides grid & sizing

4.3 Touch, swipe & resistance

4.4 Swiping behavior & clicks

4.5 Progress, loop & rewind

4.6 Effects (selector + per-effect blocks)

Warning

cssMode: true swaps Swiper's JS-driven movement for the browser's CSS Scroll Snap. It can be much faster for simple sliders but does not support: Cube effect; the speed parameter may have no effect; transition start/end events (use slideChange); limited slidesPerGroup; simulateTouch/mouse-drag; resistance; allowSlidePrev/Next; and swipeHandler. With 3D effects you must wrap slide content in <div class="swiper-slide-transform">.

The per-effect option objects (fadeEffect, cubeEffect, coverflowEffect, flipEffect, cardsEffect, creativeEffect) are fully documented in §6.

4.7 Responsive & observation

4.8 Element / Web Component parameters

4.9 CSS class-name parameters (namespacing)

Each of these overrides a default Swiper CSS class. Defaults shown; changing them requires matching CSS changes. (Marked * are not supported in the React/Vue components.)

4.10 Event registration parameters

Note

Negative knowledge The following do not exist as core options and should never be documented as such: there is no lazy core option (lazy loading is handled via lazyPreloadPrevNext + the swiper-lazy-preloader element and per-slide markup), no autoplay core boolean independent of the Autoplay module, and no top-level navigation/pagination/scrollbar behavior without importing the matching module. The only build-time variable is SWIPER_BUILD_MODULES; there are no runtime env vars.

5. Complete Events Reference

Core events from src/types/swiper-events.d.ts. Handlers receive the swiper instance as the first argument (plus any listed extras). Register via the on option, swiper.on(name, handler), .once(), or .off().

5.1 Lifecycle events

5.2 Slide-change events

5.3 Transition & translate events

5.4 Pointer / interaction events

Each receives (swiper, event) where event is a MouseEvent \| TouchEvent \| PointerEvent (except sliderFirstMove, which receives a TouchEvent):

touchStart, touchMove, touchMoveOpposite, sliderMove, sliderFirstMove, touchEnd, click, tap, doubleTap, doubleClick.

5.5 Position / edge events

5.6 Layout / structural events

Note

Events prefixed with _ (e.g. _beforeBreakpoint, _containerClasses, _slideClass, _swiper, _freeModeNoMomentumRelease) are internal. They are emitted for internal/integration plumbing and are not part of the stable public API — do not rely on them.

Module events (e.g. autoplayStart, navigationNext, paginationRender, zoomChange, hashChange, scrollbarDragMove, keyPress, scroll) are listed with their modules in §6.

6. Module Reference

For each module: its option object (with defaults), the instance methods it adds, and the events it emits. Source: src/types/modules/*.d.ts.

6.1 Navigation

Options: enabled?, nextEl/prevEl (null), addIcons (true), hideOnClick (false), disabledClass ('swiper-button-disabled'), hiddenClass ('swiper-button-hidden'), lockClass ('swiper-button-lock'), navigationDisabledClass ('swiper-navigation-disabled'). Instance (swiper.navigation): nextEl, prevEl, update(), init(), destroy(). Events: navigationShow, navigationHide, navigationPrev, navigationNext.

6.2 Pagination

Options: enabled?, el (null), type ('bullets'), bulletElement ('span'), dynamicBullets (false), dynamicMainBullets (1), hideOnClick (true), clickable (false), progressbarOpposite (false), render hooks renderBullet/renderFraction/renderProgressbar/renderCustom, formatFractionCurrent/formatFractionTotal, plus class names: bulletClass ('swiper-pagination-bullet'), bulletActiveClass ('swiper-pagination-bullet-active'), modifierClass ('swiper-pagination-'), currentClass, totalClass, hiddenClass, progressbarFillClass, progressbarOppositeClass, clickableClass, lockClass, horizontalClass, verticalClass, paginationDisabledClass. Instance (swiper.pagination): el, bullets[], render(), update(), init(), destroy(). Events: paginationRender, paginationUpdate, paginationShow, paginationHide.

6.3 Scrollbar

Options: enabled?, el (null), hide (true), draggable (false), snapOnRelease (false), dragSize ('auto'), lockClass ('swiper-scrollbar-lock'), dragClass ('swiper-scrollbar-drag'), scrollbarDisabledClass, horizontalClass, verticalClass. Instance (swiper.scrollbar): el, dragEl, updateSize(), setTranslate(), init(), destroy(). Events: scrollbarDragStart, scrollbarDragMove, scrollbarDragEnd (each receives the pointer event).

6.4 Autoplay

Options: delay (3000), stopOnLastSlide (false), disableOnInteraction (true), reverseDirection (false), waitForTransition (true), pauseOnMouseEnter (false). Instance (swiper.autoplay): running, paused, timeLeft, start(), stop(), pause(), resume(). Events: autoplayStart, autoplayStop, autoplayPause, autoplayResume, autoplay, autoplayTimeLeft(swiper, timeLeft, percentage). Per-slide override: data-swiper-autoplay="<ms>".

6.5 Keyboard

Options: enabled (false), onlyInViewport (true), pageUpDown (true), speed. Instance (swiper.keyboard): enabled, enable(), disable(). Events: keyPress(swiper, keyCode).

6.6 Mousewheel

Options: enabled (false), forceToAxis (false), releaseOnEdges (false), invert (false), sensitivity (1), eventsTarget ('container'), thresholdDelta (null), thresholdTime (null), noMousewheelClass ('swiper-no-mousewheel'). Instance (swiper.mousewheel): enabled, enable(), disable(). Events: scroll(swiper, WheelEvent).

6.7 Zoom

Options: limitToOriginalSize (false), maxRatio (3), minRatio (1), panOnMouseMove (false), toggle (true), containerClass ('swiper-zoom-container'), zoomedSlideClass ('swiper-slide-zoomed'). Instance (swiper.zoom): enabled, scale, enable(), disable(), in(ratio?), out(), toggle(event?). Events: zoomChange(swiper, scale, imageEl, slideEl).

6.8 Thumbs

Options: swiper (null — a Swiper instance, selector, or params), slideThumbActiveClass ('swiper-slide-thumb-active'), thumbsContainerClass ('swiper-thumbs'), multipleActiveThumbs (true), autoScrollOffset (0). Instance (swiper.thumbs): swiper, update(initial, p?), init().

6.9 Virtual

Options: enabled (false), slides ([]), slidesPerViewAutoSlideSize (320), cache (true), addSlidesBefore (0), addSlidesAfter (0), renderSlide (null), renderExternal (null), renderExternalUpdate (true). Instance (swiper.virtual): cache, from, to, slides[], appendSlide(), prependSlide(), removeSlide(), removeAllSlides(), update(force).

6.10 Free Mode

Options: enabled (false), momentum (true), momentumRatio (1), momentumVelocityRatio (1), momentumBounce (true), momentumBounceRatio (1), minimumVelocity (0.02), sticky (false). Instance (swiper.freeMode): onTouchMove(), onTouchEnd().

6.11 Grid

Options: rows (1), fill ('column' — 'row' or 'column').

6.12 Controller

Options: control (Swiper instance(s), selector, or element — null), inverse (false), by ('slide' — 'slide' or 'container'). Instance (swiper.controller): control.

6.13 A11y

Options (enabled by default): enabled (true), prevSlideMessage ('Previous slide'), nextSlideMessage ('Next slide'), firstSlideMessage ('This is the first slide'), lastSlideMessage ('This is the last slide'), paginationBulletMessage ('Go to slide {{index}}'), notificationClass ('swiper-notification'), containerMessage (null), containerRoleDescriptionMessage (null), containerRole (null), itemRoleDescriptionMessage (null), slideLabelMessage ('{{index}} / {{slidesLength}}'), slideRole ('group'), id (null), scrollOnFocus (true), wrapperLiveRegion (true). Placeholders: {{index}}, {{slidesLength}}.

6.14 Hash Navigation

Options: watchState (false), replaceState (false), getSlideIndex(swiper, hash) (for virtual slides). Events: hashChange, hashSet.

6.15 History

Options: enabled (false), root (''), replaceState (false), key ('slides'), keepQuery (false). Per-slide URL segment via data-history="<value>".

6.16 Parallax

Options: enabled (false). Parallaxed elements inside slides use data-swiper-parallax* attributes.

6.17 Manipulation (core only)

Adds slide-editing methods to the instance: appendSlide(), prependSlide(), addSlide(index, slides), removeSlide(indexOrIndexes), removeAllSlides(). Accepts HTML strings or HTMLElement(s). In React/Vue, manipulate the data source instead.

6.18 Effect modules

The EffectCreative prev/next transform shape: { translate?: (string|number)[]; rotate?: number[]; opacity?: number; scale?: number; shadow?: boolean; origin?: string }.

7. Instance API (Swiper class)

From src/types/swiper-class.d.ts.

7.1 Construction & statics

new Swiper(container: CSSSelector | HTMLElement, options?: SwiperOptions)

7.2 Navigation methods

7.3 Update / layout methods

update(), updateSize(), updateSlides(), updateProgress(), updateSlidesClasses(), updateAutoHeight(speed?), slidesPerViewDynamic(), changeDirection(direction?, needUpdate?), changeLanguageDirection('rtl' | 'ltr').

7.4 Translate methods

setTranslate(value), getTranslate(), translateTo(translate, speed, runCallbacks?, translateBounds?), minTranslate(), maxTranslate(), setGrabCursor(), unsetGrabCursor().

7.5 Lifecycle & events methods

init(el?), destroy(deleteInstance?, cleanStyles?), enable(), disable(), attachEvents(), detachEvents(), on(event, handler), once(event, handler), off(event, handler?), emit(event, ...args), onAny(handler), offAny(handler).

7.6 Key instance properties (read state)

Note

Properties documented !INTERNAL in the source (loopedSlides, rtlTranslate, currentBreakpoint, destroyed, modules, loopCreate(), loopDestroy(), isHorizontal(), getBreakpoint(), setBreakpoint()) are implementation details and not part of the supported public API.

8. Styling & CSS Contract

8.1 Required structure & default classes

<div class="swiper">
  <div class="swiper-wrapper">
    <div class="swiper-slide">...</div>
    <div class="swiper-slide">...</div>
  </div>
  <!-- optional module elements -->
  <div class="swiper-button-prev"></div>
  <div class="swiper-button-next"></div>
  <div class="swiper-pagination"></div>
  <div class="swiper-scrollbar"></div>
</div>

Swiper computes state classes on slides at runtime: swiper-slide-active, swiper-slide-next, swiper-slide-prev, swiper-slide-visible, swiper-slide-fully-visible, swiper-slide-blank, swiper-slide-zoomed, and container modifier classes prefixed swiper- (direction, effect, RTL, locked, etc.). Module elements get their own state classes (e.g. swiper-button-disabled, swiper-pagination-bullet-active).

8.2 Light DOM vs Shadow DOM

Two parallel CSS sets exist:

• Light DOM (swiper/css, swiper/css/<module>) — for the core/React/Vue usage where slides are in the normal document.
• Shadow DOM (swiper/element/css/<module>, files suffixed -element) — for the <swiper-container> web component, whose internals are encapsulated. Inject these via injectStyles/injectStylesUrls.

Important

A recurring community request (issue #8164) asks Swiper to ship its built-in classes at 0 CSS specificity so apps can override them more easily. When theming, prefer overriding via the documented class-name parameters (§4.9) or layering your own classes rather than fighting specificity.

9. Security

Swiper is a client-side UI library: it has no server component, no network calls, no filesystem access, no credentials, and no environment-variable configuration. The attack surface is therefore limited to what runs in the user's browser when slides and options are rendered. Key considerations:

9.1 Known vulnerability class — prototype pollution

The project's issue tracker shows active security work in the prototype pollution class:

• #8189 — "Incomplete Fix for CVE-2026-27212" (open): indicates a follow-up to a previously addressed CVE; the fix was reported as incomplete and is under review.
• #8167 — "Can you backport the prototype pollution fix to v11?" (closed): a prototype-pollution fix landed and a backport to the v11 line was requested.

Implication for integrators:

Caution

Prototype-pollution issues in a slider typically arise when untrusted data is merged into the options object (deep-merge of attacker-controlled keys like __proto__). If you build Swiper options from user-supplied or third-party JSON, sanitize keys before passing them to new Swiper(...), and stay on the latest patched v12.x release. Track issue #8189 for the current state of CVE-2026-27212.

9.2 DOM injection through render hooks

Several options accept HTML strings or render functions that produce HTML: pagination.renderBullet/renderFraction/renderProgressbar/renderCustom, virtual.renderSlide/renderExternal, and the Manipulation methods (appendSlide, prependSlide, addSlide) accept raw HTML strings.

Warning

Treat all of these as innerHTML sinks. Never pass unescaped user content into render hooks or appendSlide/addSlide. Escape or sanitize first, or build HTMLElements yourself rather than passing HTML strings.

9.3 Web component & Shadow DOM

The <swiper-container> element injects styles into a Shadow Root. One closed community issue (#8169) reported a NotAllowedError setting adoptedStyleSheets on a ShadowRoot in certain environments — a robustness rather than confidentiality concern, but worth noting for constrained runtimes (e.g. some embedded/CSP-restricted contexts).

9.4 Hardening checklist

• [ ] Pin to the latest patched swiper@12 release; watch the tracker for CVE follow-ups.
• [ ] Sanitize any externally sourced data before it reaches the options object (guard against __proto__/constructor keys).
• [ ] Sanitize/escape content used in renderBullet/renderSlide/appendSlide/addSlide.
• [ ] Apply a Content Security Policy; Swiper does not require eval or remote script.
• [ ] If embedding via the web component, verify adoptedStyleSheets support in your target runtimes.

10. Performance Tuning

Tip

For content- or image-heavy carousels with many slides, the highest-impact change is the Virtual module. For simple sliders that don't need Swiper's richer features, cssMode can substantially reduce JS work.

11. Development & Contributing

• Edit source only. Per the README, all changes go into src/; dist/ is generated and must not be hand-edited.
• Source of truth for the API is the TypeScript declarations under src/types/ — option/method/event descriptions and defaults live in their JSDoc.
• Validate before committing: npm run validate (Prettier check + ESLint). The full npm test runs validate then a production build.
• Playgrounds: npm run core | react | vue | element build and serve the matching example app under playground/ via Vite; npm run demos serves the broader demos/ site. Use these to manually verify behavior across all four targets.
• Releases: npm run release runs validation then the release script; npm run changelog regenerates CHANGELOG.md using the Angular conventional-changelog preset.
• Conventions: ESLint (airbnb-base) + Prettier are enforced; the codebase is ESM-only.

12. Known Issues & Improvement Areas

Drawn from the project's issue tracker (community-reported). These reflect real, open friction points an integrator may encounter and a maintainer may prioritize.

12.1 Loop mode

Loop mode is the most frequent source of open issues:

• #8076 — loop mode not working correctly in some configurations.
• #7586 — Swiper warns about a "wrong number of slides for loop mode" even when the count seems valid.
• #8178 — loopAdditionalSlides doesn't behave as expected in certain conditions.
• #7478 / #8095 — slideToClickedSlide + centeredSlides + loop interactions break the loop or block link clicks.
• #7254 — request to set a fixed number of duplicated slides to stabilize loop behavior.

Note

The recurring theme: loop's slide-rearrangement interacts badly with centeredSlides, slideToClickedSlide, and fractional slidesPerView. When auditing a looped slider, test these combinations explicitly and prefer realIndex/slideToLoop in app code.

12.2 Accessibility

• #8181 — improve accessibility in loop mode.
• #7975 — redundant aria-disabled added alongside the native disabled attribute on navigation buttons.
• #5844 — option to disable the span.swiper-notification live region.

12.3 Web component (Element) parity

• #8125 — <swiper-container> doesn't render the last two slides with loop + slidesPerView="auto" + custom slide width.
• #7151 — pagination dots malfunction in loop mode in the Svelte/Element integration.
• #8173 — request to expose isEnd/isBeginning state on the host element for CSS styling.

12.4 Effects & rendering

• #8168 — Cube (and possibly other) effects show graphics glitches on Electron/WebKit.
• #8161 — pagination button icons slightly clipped.

12.5 Feature requests of note

• #8086 / #6882 — desktop zoom and single-click zoom enhancements.
• #8174 — expose isFullyVisible in the React SwiperSlide render props.
• #8164 — ship built-in classes at 0 specificity for easier overriding.

12.6 Maintainer-facing observations

• Loop semantics need clearer guardrails. Several issues stem from users not satisfying loop's slide-count requirements; surfacing the requirement earlier (or auto-correcting more aggressively than loopAddBlankSlides) would reduce churn.
• Element/web-component parity lags the React/Vue wrappers in a few cases (last-slides rendering, pagination in loop, exposing state to the host). Integrators targeting the web component should test the specific feature combinations above.
• Security follow-through. With an open "incomplete fix" on a CVE (#8189), integrators should pin to the latest patch and maintainers should prioritize closing the prototype-pollution thread and backports.

13. Quick Reference