nuxt-swiper
Version:
[](https://www.npmjs.com/package/nuxt-swiper/) [](https://www.npmjs.com/package/nuxt-swiper) [ • 5.78 kB
Markdown
# Nuxt Swiper
[](https://www.npmjs.com/package/nuxt-swiper/)
[](https://www.npmjs.com/package/nuxt-swiper)
[](/LICENSE)
> [!IMPORTANT]
> **_Nuxt Swiper_** utilizes Swiper.js as its foundation using its web components. Please ensure that you read the Swiper.js [documentation](https://swiperjs.com/element) 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](https://github.com/nolimits4web/swiper/issues).
> [!NOTE]
> If you want to learn how to use web components in **Vue.js** please refer to the docs here: [Vue.js Web Components](https://vuejs.org/guide/extras/web-components.html)
## Features
- 📖 Open Source
- 🪄 TypeScript Support
- ✅ Auto Imports Enabled
- ✨ Just Works Out of the Box like Magic
## Setup
### Try it online
[](https://stackblitz.com/github/cpreston321/nuxt-swiper/tree/main/examples/swiper-basic?file=app.vue)
### Step 1: Install module
```bash
npx 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
````ts
interface ModuleOptions {
/**
* Enable custom Swiper composables to help you access Swiper instance.
* @example ```vue
* <script setup>
* const swiperRef = ref<null>(null)
* const swiper = useSwiper(swiperRef, { loop: true, autoplay: { delay: 5000 })
*
* const next = () => swiper.next()
* </script>
*
* <template>
* <swiper-container ref="swiperRef" :init="false">
* <swiper-slide>Slide 1</swiper-slide>
* <swiper-slide>Slide 2</swiper-slide>
* </swiper-container>
* </template>
* ```
* @default true
*/
enableComposables?: boolean
/**
* Bundle Swiper custom elements.
* if disabled, you need to import swiper css and modules manually.
* @see https://swiperjs.com/element#core-version--modules
* @default true
*/
bundled?: boolean
}
````
### Basic Usage
```vue
<script setup lang="ts">
// Create 10 slides
const containerRef = ref(null)
const slides = ref(Array.from({ length: 10 }))
const swiper = useSwiper(containerRef)
onMounted(() => {
// Access Swiper instance
// Read more about Swiper instance: https://swiperjs.com/swiper-api#methods--properties
console.log(swiper.instance)
})
</script>
<template>
<ClientOnly>
<swiper-container ref="containerRef">
<swiper-slide
v-for="(slide, idx) in slides"
:key="idx"
style="background-color: rgb(32, 233, 70); color: white;"
>
Slide {{ idx + 1 }}
</swiper-slide>
</swiper-container>
</ClientOnly>
<!-- Go back one slide -->
<button @click="swiper.prev()">Prev</button>
<!-- Go forward one slide -->
<button @click="swiper.next()">Next</button>
</template>
<style lang="css">
swiper-slide {
display: flex;
justify-content: center;
align-items: center;
font-size: 18px;
height: 20vh;
font-size: 4rem;
font-weight: bold;
font-family: 'Roboto', sans-serif;
}
</style>
```
## Advanced Usage
```vue
<script setup lang="ts">
const containerRef = ref(null)
const slides = ref(Array.from({ length: 10 }))
const swiper = useSwiper(containerRef, {
effect: 'creative',
loop: true,
autoplay: {
delay: 5000,
},
creativeEffect: {
prev: {
shadow: true,
translate: [0, 0, -400],
},
next: {
shadow: true,
translate: [0, 0, -400],
},
},
})
onMounted(() => {
console.log(swiper.instance)
})
</script>
<template>
<ClientOnly>
<swiper-container ref="containerRef" :init="false">
<swiper-slide
v-for="(slide, idx) in slides"
:key="idx"
style="background-color: rgb(32, 233, 70); color: white;"
>
Slide {{ idx + 1 }}
</swiper-slide>
</swiper-container>
</ClientOnly>
</template>
<style lang="css">
swiper-slide {
display: flex;
justify-content: center;
align-items: center;
font-size: 18px;
height: 20vh;
font-size: 4rem;
font-weight: bold;
font-family: 'Roboto', sans-serif;
}
</style>
```
## 💻 Development
<details>
<summary>Local development</summary>
- Clone this repository
- Install the latest LTS version of [Node.js](https://nodejs.org/en/)
- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
- Install dependencies using `pnpm install`
- Generate type stubs using `pnpm dev:prepare`
- Run tests using `pnpm dev`
</details>
## Credits
[`Swiper.js`](https://swiperjs.com/) is developed by [@nolimits4web](https://github.com/nolimits4web).
[`Nuxt Swiper`](#nuxt-swiper) is developed by [@cpreston321](https://github.com/cpreston321).
## 📧 Contact
**X** (formely knowned as Twitter) - [@christian_ggg](https://x.com/christian_ggg)
Also, if you like my work, please feel free to [buy me a coffee](https://www.buymeacoffee.com/cpreston321) ☕️
[](https://www.buymeacoffee.com/cpreston321)
## Contributors
[](https://contrib.rocks/image?repo=cpreston321/nuxt-swiper)
---
[MIT](./LICENSE) License © 2025 [CP](https://github.com/cpreston321)