DOCSEARCHbyAlgolia
Submit Docs

Nuxt Swiper

repository·main·Indexed 43 days ago

https://github.com/cpreston321/nuxt-swiper

A Nuxt module for integrating Swiper.js using its Web Component implementation. Version 2.0.2 features auto-imports, TypeScript support, and the useSwiper composable for programmatic control of <swiper-container> and <swiper-slide> elements.

Tokens
2.1K
Snippets
10
Records
10
Agent score
55%

What's inside Nuxt Swiper

  1. Use Swiper web components in Nuxt

    main

    Nuxt Swiper uses Swiper.js web components. Because they are web components, you must use kebab-case naming conventions in your templates instead of the standard Vue camelCase.

    Available components:

    • <swiper-container />
    • <swiper-slide />

    Important: Since these are web components, it is highly recommended to wrap them in <ClientOnly> to prevent hydration mismatches, as they rely on browser APIs.

    <template>
  <ClientOnly>
    <swiper-container>
      <swiper-slide>Slide 1</swiper-slide>
    </swiper-container>
  </ClientOnly>
</template>

  6. Configure Nuxt Swiper module options

    main

    You can configure the module in your nuxt.config.ts. The following options are available:

    OptionTypeDefaultDescription
    enableComposablesbooleantrueEnables custom Swiper composables (like useSwiper) to help you access the Swiper instance.
    bundledbooleantrueWhether to bundle Swiper custom elements. If false, you must manually import Swiper CSS and modules.
    interface ModuleOptions {
  enableComposables?: boolean
  bundled?: boolean
}

  7. Basic Swiper usage example

    main

    A simple implementation using useSwiper to control navigation (Prev/Next) via buttons.

    <script setup lang="ts">
const containerRef = ref(null)
const slides = ref(Array.from({ length: 10 }))
const swiper = useSwiper(containerRef)

onMounted(() => {
  console.log(swiper.instance)
})
</script>

<template>
  <ClientOnly>
    <swiper-container ref="containerRef">
      <swiper-slide
        v-for="(slide, idx) in slides"
        :key="idx"
      >
        Slide {{ idx + 1 }}
      </swiper-slide>
    </swiper-container>
  </ClientOnly>

  <button @click="swiper.prev()">Prev</button>
  <button @click="swiper.next()">Next</button>
</template>

  8. Access the Swiper instance with useSwiper

    main

    The useSwiper composable allows you to interact with the Swiper instance programmatically. You pass a template ref to the container and an optional configuration object.

    To use useSwiper with custom settings, set :init="false" on the <swiper-container> to prevent it from initializing before your configuration is applied.

    <script setup lang="ts">
const containerRef = ref(null)
const swiper = useSwiper(containerRef, {
  effect: 'creative',
  loop: true,
  autoplay: { delay: 5000 },
})

onMounted(() => {
  // Access the underlying Swiper instance
  console.log(swiper.instance)
})
</script>

<template>
  <ClientOnly>
    <swiper-container ref="containerRef" :init="false">
      <swiper-slide>Slide 1</swiper-slide>
    </swiper-container>
  </ClientOnly>
</template>

  9. Use the useSwiper composable

    main

    When enableComposables is set to true (the default), you can use the useSwiper composable to gain programmatic control over a Swiper instance.

    To use it, pass a template ref pointing to the <swiper-container> element. Note that you should set :init="false" on the <swiper-container> if you intend to initialize or control it via the composable manually.

    Example

    <script setup>
const swiperRef = ref<null>(null)
// Pass the ref and any Swiper configuration options
const swiper = useSwiper(swiperRef, { loop: true, autoplay: { delay: 5000 } })

const next = () => swiper.next()
</script>

<template>
  <!-- Use :init="false" to allow the composable to manage initialization -->
  <swiper-container ref="swiperRef" :init="false">
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
  </swiper-container>
  
  <button @click="next">Next</button>
</template>
    <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>

  10. Use the useSwiper composable to control Swiper instances

    main

    The useSwiper composable provides a reactive interface to a <swiper-container> element. It allows you to access the underlying Swiper instance, monitor its state (like current index or progress), and trigger navigation methods (like next, prev, or to) directly from your Vue component logic.

    Parameters

    • swiperContainerRef: A Vue Ref pointing to the <swiper-container> element.
    • options (optional): An object containing Swiper configuration parameters. If provided, these options are automatically applied to the container and the Swiper instance is initialized.

    Returned Properties

    Instance

    • instance: A Ref containing the actual Swiper instance.

    Reactive State

    These properties update automatically as the slider moves:

    • isBeginning: true if the slider is at the first slide.
    • isEnd: true if the slider is at the last slide.
    • activeIndex: The index of the currently active slide.
    • realIndex: The index of the currently active slide (useful when using loop: true).
    • slides: An array of the current slides.
    • slidesPerView: The number of slides visible.
    • progress: The current progress of the slider.
    • getNumberOfSlides: The total number of slides.

    Navigation Methods

    • next(...params): Transitions to the next slide.
    • prev(...params): Transitions to the previous slide.
    • to(...params): Transitions to a specific slide index.
    • reset(...params): Resets the swiper position to the currently active slide.
    • reInitialize(): Re-runs the initialization logic.
    <script setup>
import { ref } from 'vue'

const swiperRef = ref(null)
const { next, prev, isBeginning, isEnd } = useSwiper(swiperRef, {
  slidesPerView: 1,
  spaceBetween: 10,
})
</script>

<template>
  <swiper-container ref="swiperRef">
    <swiper-slide>Slide 1</swiper-slide>
    <swiper-slide>Slide 2</swiper-slide>
  </swiper-container>

  <button @click="next" :disabled="isEnd">Next</button>
  <button @click="prev" :disabled="isBeginning">Previous</button>
</template>