Vue Awesome Swiper (Deprecated)

5.0.1 · deprecated · verified Sun Apr 19

Vue Awesome Swiper is a Vue.js component wrapper for the Swiper carousel library. As of its latest stable version, 5.0.1, the project is officially deprecated. Version 5.x acts exclusively as a re-export of the official `swiper/vue` package, making its APIs entirely incompatible with previous `vue-awesome-swiper` versions (v4.x and below). All functionality and component structures now directly mirror the official Swiper Vue component. Developers are strongly advised to migrate to the official `swiper/vue` package for continued stability, features, and future updates. Prior versions (e.g., v4.1.1 for Swiper 5-6/Vue 2, v3.1.3 for Swiper 4.x/Vue 2) offered direct integration but are no longer maintained. The project effectively has no independent release cadence since its deprecation, simply following `swiper/vue`'s exports.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'use')
```
cause Attempting to use `SwiperClass.use()` or other methods from an incorrectly imported Swiper instance, often after migrating from `vue-awesome-swiper` v4.x to v5.x without updating module imports.

fix For `vue-awesome-swiper` v5.x (and `swiper/vue`), Swiper modules are passed as props to the `<swiper>` component via the `modules` array (e.g., `:modules="[Pagination, Navigation]"`). Ensure modules are imported directly from `swiper` and passed correctly.
```
Vue warn: Component is missing template or render function.
```
cause This typically occurs when trying to use `vue-awesome-swiper` v5.x components in a Vue 2 project or incorrectly configuring a Vue 3 project with incompatible component versions or build setups.

fix Verify that your project is running Vue 3.x, as `vue-awesome-swiper` v5.x (and `swiper/vue`) are Vue 3-only. If you need Vue 2 support, you must use `vue-awesome-swiper@4.1.1` or earlier.

Warnings

breaking Version 5.x of `vue-awesome-swiper` introduces a complete API incompatibility with previous versions (v4.x and below). It no longer provides its own Swiper wrapper but instead re-exports components directly from the official `swiper/vue` package. Code written for older `vue-awesome-swiper` APIs will not function with v5.x.
Fix: Rewrite your Swiper component usage to align with the `swiper/vue` API documentation. This involves using `Swiper` and `SwiperSlide` components directly, importing modules and styles from the `swiper` package, and adopting the new prop and event structure.
deprecated The `vue-awesome-swiper` library is officially deprecated as of version 5.x. Users are strongly recommended to migrate to the official `swiper/vue` component for ongoing support, new features, and bug fixes, as this project will not receive further independent development.
Fix: Update your import paths to use `import { Swiper, SwiperSlide } from 'swiper/vue'` instead of `vue-awesome-swiper`. No other changes are typically needed for v5.x code as it already re-exports the official components.
gotcha When using `vue-awesome-swiper` v5.x, all Swiper modules (e.g., Pagination, Navigation) and their corresponding CSS styles must be imported directly from the `swiper` package, not from `vue-awesome-swiper`. Forgetting to import styles will result in unstyled carousels.
Fix: Ensure you explicitly import Swiper modules (e.g., `import { Pagination } from 'swiper'`) and all necessary CSS files (e.g., `import 'swiper/css'`, `import 'swiper/css/pagination'`) in your component or global entry point.

Install

npm install vue-awesome-swiper npm
yarn add vue-awesome-swiper yarn
pnpm add vue-awesome-swiper pnpm

Imports

Swiper, SwiperSlide
wrong:
```
const { Swiper, SwiperSlide } = require('vue-awesome-swiper')
```
correct:
```
import { Swiper, SwiperSlide } from 'vue-awesome-swiper'
```
Since v5, `vue-awesome-swiper` re-exports from `swiper/vue`, so this is functionally equivalent to `import { Swiper, SwiperSlide } from 'swiper/vue'`. ESM is required.
Pagination (and other Swiper modules)
wrong:
```
import { Pagination } from 'vue-awesome-swiper'
```
correct:
```
import SwiperClass, { Pagination } from 'swiper'
import 'swiper/css'
import 'swiper/css/pagination'
```
Swiper modules and their CSS must be imported directly from the `swiper` package, not `vue-awesome-swiper` v5. Ensure you import the base Swiper class and specific module styles.

Quickstart

This example demonstrates the basic setup of `vue-awesome-swiper` v5.x within a Vue 3 SFC, including module imports, event handling, and basic styling for a functional carousel.

<template>
  <swiper
    :modules="modules"
    :pagination="{ clickable: true }"
    :slides-per-view="1"
    :space-between="30"
    navigation
    @swiper="onSwiper"
    @slideChange="onSlideChange"
  >
    <swiper-slide>Slide 1: Welcome to Swiper!</swiper-slide>
    <swiper-slide>Slide 2: A powerful touch slider.</swiper-slide>
    <swiper-slide>Slide 3: Build amazing carousels.</swiper-slide>
    <swiper-slide>Slide 4: Fully customizable.</swiper-slide>
  </swiper>
</template>

<script setup>
  import { ref } from 'vue';
  import SwiperClass, { Pagination, Navigation } from 'swiper';
  import { Swiper, SwiperSlide } from 'vue-awesome-swiper';

  // Import Swiper styles
  import 'swiper/css';
  import 'swiper/css/pagination';
  import 'swiper/css/navigation';

  const modules = [Pagination, Navigation];
  const swiperInstance = ref(null);

  const onSwiper = (swiper) => {
    swiperInstance.value = swiper;
    console.log('Swiper initialized:', swiper);
  };

  const onSlideChange = () => {
    console.log('Slide changed!');
  };
</script>

<style scoped>
.swiper-slide {
  display: flex;
  justify-content: center;
  align-items: center;
  font-size: 24px;
  height: 200px;
  background-color: #f0f0f0;
  border-radius: 8px;
}
</style>

view raw JSON →