n-carousel

name	n-carousel
description	Carousel component for displaying rotating content like images, banners, or cards. Invoke when user needs to implement image sliders, content carousels, or card-based navigation in Naive UI.
metadata	{"author":"jiaiyan","version":"1.0.0"}

Naive UI Carousel Component

Carousel component for displaying rotating content with various transition effects and navigation options.

When to Use

Use this component when:

• Image galleries: Display rotating images or banners
• Content sliders: Show featured content or promotions
• Card carousels: Navigate through card-based content
• Product showcases: Display products in an interactive slider

When to Invoke

Invoke this skill when:

• User needs to implement an image slider or carousel
• User wants autoplay or manual navigation features
• User needs vertical or horizontal carousel layouts
• User wants to customize transition effects (slide, fade, card)
• User asks about carousel dots, arrows, or keyboard navigation
• User needs multiple slides per view or centered slides

Features

• Direction: Horizontal or vertical layout
• Autoplay: Automatic rotation with configurable interval
• Navigation: Dots, arrows, keyboard, mousewheel, touch/drag
• Effects: Slide, fade, card, or custom transitions
• Multiple Slides: Configurable slides per view with spacing
• Loop: Continuous looping through slides
• Centered Slides: Center the active slide
• Customizable: Custom dots, arrows, and transition styles

API Reference

Carousel Props

Name	Type	Default	Description
autoplay	boolean	false	Whether to scroll automatically.
centered-slides	boolean	false	Whether to center the current view carousel.
current-index	number	undefined	Current index (controlled).
default-index	number	0	Default index.
direction	'horizontal' | 'vertical'	'horizontal'	Carousel shows the direction.
dot-placement	'top' | 'bottom' | 'left' | 'right'	'bottom'	Dot placement in the panel.
dot-type	'dot' | 'line'	'dot'	Dot style.
draggable	boolean	false	Whether to switch by dragging the mouse.
effect	'slide' | 'fade' | 'card' | 'custom'	'slide'	Transition effect.
interval	number	5000	Auto play interval (ms).
keyboard	boolean	false	Whether to switch by keyboard (focus on Dots).
loop	boolean	true	Whether to loop.
mousewheel	boolean	false	Whether to switch through mouse wheel.
next-slide-style	object | string	undefined	Next slide's style (for card effect).
prev-slide-style	object | string	undefined	Previous slide's style (for card effect).
show-arrow	boolean	false	Whether to show arrow buttons.
show-dots	boolean	true	Whether to show dots.
slides-per-view	'auto' | number	1	Number of carousels displayed per view.
space-between	number	0	The spacing between carousels.
touchable	boolean	true	Whether to switch by touch.
transition-style	object	{ transitionDuration: '300ms' }	Transition style.
transition-props	TransitionProps	undefined	Custom transition effect properties.
trigger	'click' | 'hover'	'click'	The method of manual switching.
on-update:current-index	(currentIndex: number, lastIndex: number) => void	undefined	Callback when index changes.

Carousel Slots

Name	Parameters	Description
default	()	Carousel content.
arrow	{ total, currentIndex, to, prev, next }	Custom arrow.
dots	{ total, currentIndex, to }	Custom dots.

Carousel Methods

Name	Type	Description
to	(index: number) => void	Slide to index.
prev	() => void	Slide to previous page.
next	() => void	Slide to next page.
getCurrentIndex	() => number	Get current index.

Basic Usage

Basic Carousel

<template>
  <n-carousel>
    <img
      class="carousel-img"
      src="https://naive-ui.oss-cn-beijing.aliyuncs.com/carousel-img/carousel1.jpeg"
    />
    <img
      class="carousel-img"
      src="https://naive-ui.oss-cn-beijing.aliyuncs.com/carousel-img/carousel2.jpeg"
    />
    <img
      class="carousel-img"
      src="https://naive-ui.oss-cn-beijing.aliyuncs.com/carousel-img/carousel3.jpeg"
    />
  </n-carousel>
</template>

<style scoped>
.carousel-img {
  width: 100%;
  height: 240px;
  object-fit: cover;
}
</style>

Autoplay with Arrows

<template>
  <n-carousel show-arrow autoplay>
    <img
      class="carousel-img"
      src="https://naive-ui.oss-cn-beijing.aliyuncs.com/carousel-img/carousel1.jpeg"
    />
    <img
      class="carousel-img"
      src="https://naive-ui.oss-cn-beijing.aliyuncs.com/carousel-img/carousel2.jpeg"
    />
    <img
      class="carousel-img"
      src="https://naive-ui.oss-cn-beijing.aliyuncs.com/carousel-img/carousel3.jpeg"
    />
  </n-carousel>
</template>

Vertical Carousel

<template>
  <n-carousel
    direction="vertical"
    dot-placement="right"
    style="width: 100%; height: 240px"
  >
    <img class="carousel-img" src="image1.jpeg" />
    <img class="carousel-img" src="image2.jpeg" />
    <img class="carousel-img" src="image3.jpeg" />
  </n-carousel>
</template>

Common Patterns

Multiple Slides Per View

<template>
  <n-carousel :slides-per-view="3" :space-between="20" :loop="false" draggable>
    <img class="carousel-img" src="image1.jpeg" />
    <img class="carousel-img" src="image2.jpeg" />
    <img class="carousel-img" src="image3.jpeg" />
    <img class="carousel-img" src="image4.jpeg" />
  </n-carousel>
</template>

Card Effect

<template>
  <n-carousel
    effect="card"
    prev-slide-style="transform: translateX(-150%) translateZ(-800px);"
    next-slide-style="transform: translateX(50%) translateZ(-800px);"
    style="height: 240px"
    :show-dots="false"
  >
    <n-carousel-item :style="{ width: '60%' }">
      <img class="carousel-img" src="image1.jpeg" />
    </n-carousel-item>
    <n-carousel-item :style="{ width: '60%' }">
      <img class="carousel-img" src="image2.jpeg" />
    </n-carousel-item>
    <n-carousel-item :style="{ width: '60%' }">
      <img class="carousel-img" src="image3.jpeg" />
    </n-carousel-item>
  </n-carousel>
</template>

Custom Dots and Arrows

<template>
  <n-carousel show-arrow autoplay>
    <img class="carousel-img" src="image1.jpeg" />
    <img class="carousel-img" src="image2.jpeg" />
    <img class="carousel-img" src="image3.jpeg" />

    <template #arrow="{ prev, next }">
      <div class="custom-arrow">
        <button type="button" class="custom-arrow--left" @click="prev">
          <n-icon><ArrowBack /></n-icon>
        </button>
        <button type="button" class="custom-arrow--right" @click="next">
          <n-icon><ArrowForward /></n-icon>
        </button>
      </div>
    </template>

    <template #dots="{ total, currentIndex }">
      <span class="custom-dots"> {{ currentIndex + 1 }} / {{ total }} </span>
    </template>
  </n-carousel>
</template>

Custom Transition Effect

<template>
  <n-carousel
    effect="custom"
    :transition-props="{ name: 'creative' }"
    show-arrow
    style="width: 100%; height: 240px"
  >
    <img class="carousel-img" src="image1.jpeg" />
    <img class="carousel-img" src="image2.jpeg" />
    <img class="carousel-img" src="image3.jpeg" />
  </n-carousel>
</template>

<style scoped>
:deep(.creative-enter-from),
:deep(.creative-leave-to) {
  opacity: 0;
  transform: scale(0.8);
}

:deep(.creative-enter-active),
:deep(.creative-leave-active) {
  transition: all 0.3s ease;
}
</style>

Controlled Carousel

<template>
  <n-space vertical>
    <n-carousel v-model:current-index="currentIndex" ref="carouselRef">
      <img class="carousel-img" src="image1.jpeg" />
      <img class="carousel-img" src="image2.jpeg" />
      <img class="carousel-img" src="image3.jpeg" />
    </n-carousel>

    <n-space>
      <n-button @click="carouselRef.prev()">Previous</n-button>
      <n-button @click="carouselRef.next()">Next</n-button>
      <n-button @click="carouselRef.to(0)">Go to First</n-button>
    </n-space>
  </n-space>
</template>

<script setup>
import { ref } from 'vue';

const currentIndex = ref(0);
const carouselRef = ref(null);
</script>

Best Practices

1. Set explicit height: Always set a fixed height for the carousel container

   <n-carousel style="height: 240px">
   

2. Use autoplay wisely: Set appropriate interval for user experience

   <n-carousel autoplay :interval="5000">
   

3. Responsive images: Use object-fit: cover for consistent image display

   .carousel-img {
     width: 100%;
     height: 100%;
     object-fit: cover;
   }
   

4. Disable loop with multiple slides: When using slides-per-view, disable loop

   <n-carousel :slides-per-view="3" :loop="false">
   

5. Keyboard accessibility: Enable keyboard navigation for accessibility

   <n-carousel keyboard>
   

6. Touch and drag: Enable for mobile-friendly interaction

   <n-carousel touchable draggable>
   

7. Custom navigation: Use slots for branded navigation controls