Carousel

The Carousel component cycles through images or content blocks with slide or fade animations. It supports keyboard navigation with ← and → arrow keys.

Basic Usage

Pass an array via items and bind the current index with v-model. The default animation is slide.

<script setup>
const slideItems = [
  { image: 'https://picsum.photos/seed/car1/800/400', title: 'Slide 1' },
  { image: 'https://picsum.photos/seed/car2/800/400', title: 'Slide 2' },
  { image: 'https://picsum.photos/seed/car3/800/400', title: 'Slide 3' },
]
</script>

<template>
  <TCarousel :items="slideItems" />
</template>

Fade Animation

Set animation="fade" to use a cross-fade transition instead of sliding.

<TCarousel :items="slideItems" animation="fade" />

Dot Indicators

Set indicator-style="dot" to use dot-shaped indicators instead of the default bar style.

<TCarousel :items="slideItems" indicator-style="dot" />

Thumb Indicators

Set indicator-style="thumb" to use image thumbnails as indicators.

<TCarousel :items="slideItems" indicator-style="thumb" />

Vertical Indicators

Set vertical-indicators to place the indicators vertically on the right side.

<TCarousel :items="slideItems" vertical-indicators />

Image + Overlay + Caption

Combine show-captions, caption-background, and caption-always to display readable text overlays on images with a semi-transparent dark backing.

<TCarousel :items="slideItems" :show-captions="true" :caption-background="true" caption-always />

Solid Background

Use bgColor instead of image in each item to display solid color slides. Combine with caption-background for readable text overlays.

<TCarousel :items="[
  { bgColor: '#4299e1', title: 'Blue Slide' },
  { bgColor: '#48bb78', title: 'Green Slide' },
  { bgColor: '#ed8936', title: 'Orange Slide' },
]" :show-captions="true" :caption-background="true" caption-always />

Click Event

Clicking a slide fires the @clickItem event with the current item object and its index.

<TCarousel :items="slideItems" @click-item="onSlideClick" />

<script setup>
function onSlideClick(item, index) {
  console.log('Clicked:', item, index)
}
</script>

Custom Indicators & Controls

Use the #indicators and #controls scoped slots to fully customize the indicator and navigation UI.

<TCarousel :items="slideItems" :indicators="false" :controls="false">
  <template #indicators="{ current, total }">
    <span class="badge">{{ current + 1 }} / {{ total }}</span>
  </template>
  <template #controls="{ prev, next }">
    <button @click="prev">‹ Prev</button>
    <button @click="next">Next ›</button>
  </template>
</TCarousel>

API

Props

Prop	Description	Type	Default
items	Array of carousel items	CarouselItem[]	undefined
v-model	Current active index	number	0
interval	Auto-play interval (ms), 0 to disable	number	5000
animation	Animation type	'slide' | 'fade'	'slide'
indicators	Show bottom indicators	boolean	true
indicatorStyle	Indicator style	'default' | 'dot' | 'thumb'	'default'
verticalIndicators	Place indicators vertically on the right	boolean	false
controls	Show previous/next buttons	boolean	true
pauseOnHover	Pause auto-play on hover	boolean	true
wrap	Enable infinite looping	boolean	true
showCaptions	Display title and description	boolean	false
captionAlways	Always show captions (visible on mobile)	boolean	false
captionBackground	Add dark overlay to captions	boolean	false
dark	Dark mode (invert control icons)	boolean	false
height	Fixed height	string	undefined
ariaLabel	Accessibility label	string	'Carousel'

CarouselItem

Field	Description	Type	Default
image	Image URL	string	undefined
title	Caption title	string	undefined
description	Caption description	string	undefined
bgColor	Background color (when no image)	string	undefined
html	Custom HTML content	string	undefined

Events

Event	Description	Parameters
change	Emitted when the slide changes	index: number
clickItem	Emitted when a slide is clicked	(item: CarouselItem, index: number)

Slots

Slot	Scoped Props	Description
indicators	current: number, total: number, goTo: (index) => void	Custom indicator UI
controls	prev: () => void, next: () => void, current: number, total: number	Custom navigation buttons

Keyboard Navigation

The carousel supports keyboard navigation. Focus the component and press ← (ArrowLeft) for previous slide or → (ArrowRight) for next slide.