vue3-carousel

The Carousel component utilizes specific slots to organize its content:

• Default/Slides Slot: Used to render the carousel items. You can either place Slide components directly in the default slot or wrap them in a <template #slides> block.
• Addons Slot: Used to inject UI components like <Navigation /> and <Pagination /> via the <template #addons> block.

<template>
  <Carousel>
    <template #slides>
      <Slide v-for="slide in 10" :key="slide">
        ...
      </Slide>
    </template>

    <template #addons>
      <Navigation />
      <Pagination />
    </template>
  </Carousel>
</template>

The Pagination component is built with accessibility in mind:

• Pagination buttons are properly labeled for screen readers.
• The active state is communicated via ARIA attributes.
• Buttons include descriptive titles to improve user experience.

The Navigation component provides Previous and Next buttons for slide navigation. It should be placed within the #addons slot of the Carousel component. It automatically handles RTL support, vertical navigation, and disables itself when the carousel reaches its bounds.

<script setup>
import { Navigation as CarouselNavigation } from 'vue3-carousel'
</script>

<template>
  <Carousel>
    <Slide v-for="slide in 10" :key="slide">
      <!-- slide content -->
    </Slide>
    
    <template #addons>
      <CarouselNavigation />
    </template>
  </Carousel>
</template>

The Slide component is the fundamental building block used inside a Carousel to represent individual slides. It manages visibility, positioning, and state transitions. When rendering multiple slides using v-for, always provide a unique :key to ensure correct rendering and transitions.

<template>
  <Carousel>
    <Slide v-for="slide in 10" :key="slide">
      <div class="carousel__item">
        {{ slide }}
      </div>
    </Slide>
  </Carousel>
</template>

Customize the look and feel using gap, snapAlign, slideEffect, and transitionEasing. transitionEasing accepts any valid CSS timing function.

<template>
  <!-- Custom gap, alignment, and fade effect -->
  <Carousel 
    :gap="20"
    snap-align="start"
    slide-effect="fade"
    :transition="500"
  >
    <!-- Slides -->
  </Carousel>

  <!-- Custom transition with easing -->
  <Carousel
    :transition="600"
    transition-easing="cubic-bezier(0.4, 0, 0.2, 1)"
  >
    <!-- Slides -->
  </Carousel>
</template>

Control how users interact with the carousel using autoplay, mouseDrag, touchDrag, and mouseWheel. You can also use pauseAutoplayOnHover to improve user experience.

<template>
  <Carousel 
    :autoplay="3000"
    :pause-autoplay-on-hover="true"
    :mouse-drag="true"
    :touch-drag="true"
    :mouse-wheel="{ threshold: 20 }"
  >
    <!-- Slides -->
  </Carousel>
</template>

Install the vue3-carousel package using your preferred package manager.

# npm
npm i vue3-carousel

# yarn
yarn add vue3-carousel

# pnpm
pnpm install vue3-carousel

Use itemsToShow to control visibility and itemsToScroll to define navigation steps. For vertical carousels, you must set the dir prop and provide a height.

<template>
  <!-- Basic setup with 3 items visible -->
  <Carousel :items-to-show="3" :wrap-around="true" :transition="500">
    <Slide v-for="slide in 10" :key="slide">
      Slide {{ slide }}
    </Slide>
  </Carousel>

  <!-- Vertical orientation requires a height -->
  <Carousel dir="ttb" :height="300">
    <!-- Slides -->
  </Carousel>
</template>

The Pagination component provides interactive indicators that allow users to navigate directly to specific slides. To use it, import Pagination from vue3-carousel and place it within the #addons slot of the Carousel component.

<script setup>
import { Carousel, Slide, Pagination as CarouselPagination } from 'vue3-carousel'
</script>

<template>
  <Carousel>
    <Slide v-for="slide in 10" :key="slide">
      <!-- slide content -->
    </Slide>
    
    <template #addons>
      <CarouselPagination />
    </template>
  </Carousel>
</template>

To access the internal state and data of a carousel, assign a ref to the <Carousel> component in your template. You can then access the carousel's properties through the .data property of that ref instance.

<Carousel ref="myCarousel"> ... </Carousel>

import { ref } from 'vue';
const myCarousel = ref(null);

// Access data properties via the ref
// Note: In the actual implementation, you access the exposed properties
if (myCarousel.value.currentSlide === 10) {
  // Do your magic here
}

The Carousel component is the primary container for managing slides and navigation. To use it, wrap Slide components within the Carousel. You can also include addon components like Navigation and Pagination using the #addons slot.

<template>
  <Carousel>
    <Slide v-for="slide in 10" :key="slide">
      <div class="carousel__item">{{ slide }}</div>
    </Slide>
    
    <template #addons>
      <Navigation />
      <Pagination />
    </template>
  </Carousel>
</template>