Nuxt Swiper

[!IMPORTANT] Nuxt Swiper utilizes Swiper.js as its foundation using its web components. Please ensure that you read the Swiper.js documentation before utilizing this module and reporting any issues that are not directly related to Nuxt Swiper. If there is an underlying bug, please submit an issue to the Swiper.js repository.

[!NOTE] If you want to learn how to use web components in Vue.js please refer to the docs here: Vue.js Web Components

Features

• 📖 Open Source
• 🪄 TypeScript Support
• ✅ Auto Imports Enabled
• ✨ Just Works Out of the Box like Magic

Setup

Try it online

Step 1: Install module

1npx nuxi@latest module add swiper

Usage

[!NOTE] Since these are web components, they use the kebab-case naming convention vs the camelCase naming convention that Vue uses.

Swiper Components (WebComponent)
<swiper-container/>
<swiper-slide />

Module Options

1interface ModuleOptions {
2  /**
3   * Enable custom Swiper composables to help you access Swiper instance.
4   * @example ```vue
5   * <script setup>
6   * const swiperRef = ref<null>(null)
7   * const swiper = useSwiper(swiperRef, { loop: true, autoplay: { delay: 5000 })
8   *
9   * const next = () => swiper.next()
10   * </script>
11   *
12   * <template>
13   *  <swiper-container ref="swiperRef" :init="false">
14   *    <swiper-slide>Slide 1</swiper-slide>
15   *    <swiper-slide>Slide 2</swiper-slide>
16   *  </swiper-container>
17   * </template>
18   * ```
19   * @default true
20   */
21  enableComposables?: boolean
22
23  /**
24   * Bundle Swiper custom elements.
25   * if disabled, you need to import swiper css and modules manually.
26   * @see https://swiperjs.com/element#core-version--modules
27   * @default true
28   */
29  bundled?: boolean
30}

Basic Usage

1<script setup lang="ts">
2// Create 10 slides
3const containerRef = ref(null)
4const slides = ref(Array.from({ length: 10 }))
5
6const swiper = useSwiper(containerRef)
7
8onMounted(() => {
9  // Access Swiper instance
10  // Read more about Swiper instance: https://swiperjs.com/swiper-api#methods--properties
11  console.log(swiper.instance)
12})
13</script>
14
15<template>
16  <ClientOnly>
17    <swiper-container ref="containerRef">
18      <swiper-slide
19        v-for="(slide, idx) in slides"
20        :key="idx"
21        style="background-color: rgb(32, 233, 70); color: white;"
22      >
23        Slide {{ idx + 1 }}
24      </swiper-slide>
25    </swiper-container>
26  </ClientOnly>
27
28  <!-- Go back one slide -->
29  <button @click="swiper.prev()">
30    Prev
31  </button>
32  <!-- Go forward one slide -->
33  <button @click="swiper.next()">
34    Next
35  </button>
36</template>
37
38<style lang="css">
39swiper-slide {
40  display: flex;
41  justify-content: center;
42  align-items: center;
43  font-size: 18px;
44  height: 20vh;
45  font-size: 4rem;
46  font-weight: bold;
47  font-family: 'Roboto', sans-serif;
48}
49</style>

Advanced Usage

1<script setup lang="ts">
2const containerRef = ref(null)
3const slides = ref(Array.from({ length: 10 }))
4const swiper = useSwiper(containerRef, {
5  effect: 'creative',
6  loop: true,
7  autoplay: {
8    delay: 5000,
9  },
10  creativeEffect: {
11    prev: {
12      shadow: true,
13      translate: [0, 0, -400],
14    },
15    next: {
16      shadow: true,
17      translate: [0, 0, -400],
18    },
19  },
20})
21
22onMounted(() => {
23  console.log(swiper.instance)
24})
25</script>
26
27<template>
28  <ClientOnly>
29    <swiper-container ref="containerRef" :init="false">
30      <swiper-slide
31        v-for="(slide, idx) in slides"
32        :key="idx"
33        style="background-color: rgb(32, 233, 70); color: white;"
34      >
35        Slide {{ idx + 1 }}
36      </swiper-slide>
37    </swiper-container>
38  </ClientOnly>
39</template>
40
41<style lang="css">
42swiper-slide {
43  display: flex;
44  justify-content: center;
45  align-items: center;
46  font-size: 18px;
47  height: 20vh;
48  font-size: 4rem;
49  font-weight: bold;
50  font-family: 'Roboto', sans-serif;
51}
52</style>

💻 Development

Local development

• Clone this repository
• Install the latest LTS version of Node.js
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Generate type stubs using pnpm dev:prepare
• Run tests using pnpm dev

Credits

Swiper.js is developed by @nolimits4web.

Nuxt Swiper is developed by @cpreston321.

📧 Contact

X (formely knowned as Twitter) - @christian_ggg

Also, if you like my work, please feel free to buy me a coffee ☕️

Contributors

---

MIT License © 2025 CP