Carousel

TuiCarousel is used to cycle through content such as images or text within a limited space. It supports horizontal and vertical scrolling, features a visually striking Card mode, and includes a built-in Motion Blur effect for smooth transitions.

Basic Usage

Default Mode

The most basic implementation. By default, indicators are displayed inside the container, and navigation arrows appear on hover.

<template>
  <TuiCarousel :height="250">
    <TuiCarouselItem v-for="item in 4" :key="item">
      <div class="demo-content">{{ item }}</div>
    </TuiCarouselItem>
  </TuiCarousel>
</template>

<style scoped>
.demo-content {
  width: 100%;
  height: 100%;
  background-color: var(--primary-base);
  color: white;
  display: flex;
  justify-content: center;
  align-items: center;
  font-size: 24px;
}
</style>

Appearance Modes

Card Mode

Set appearance="card" to enable card-style display.

• cardScale: Controls the scaling ratio of inactive cards (defaults to 0.8).

<TuiCarousel appearance="card" :cardScale="0.8" :height="250">
  <TuiCarouselItem v-for="item in 6" :key="item">
  </TuiCarouselItem>
</TuiCarousel>

Direction and Layout

Vertical Carousel

Set direction="v" to enable vertical scrolling. The indicators will automatically adjust their position accordingly.

<TuiCarousel direction="v" :height="400">
</TuiCarousel>

Content and Interaction

Built-in Title and Description

The TuiCarouselItem component is more than just a container; it includes a built-in mask layer and text layout for quick information display.

• title: Title text.
• description: Description text (supports multiple lines).
• hasLinkButton: Whether to show a navigation button (requires listening to the @navigateTo event).

<script setup>
const handleNavigate = (index) => {
  console.log('Jump to detail:', index);
};
</script>

<template>
  <TuiCarousel :autoplay="false">
    <TuiCarouselItem 
      v-for="(img, index) in images" 
      :key="index"
      title="This is the Title"
      description="This is a detailed description text..."
      :hasLinkButton="true"
      @navigateTo="handleNavigate(index)"
    >
      <img :src="img" style="width:100%; height:100%; object-fit:cover;" />
    </TuiCarouselItem>
  </TuiCarousel>
</template>

Motion Blur

The component enables motionBlur by default. This produces a motion blur effect during rapid transitions, significantly enhancing visual smoothness. Set :motionBlur="false" if you need to disable it for performance reasons.

Indicators and Controllers

Extensive properties are available to customize navigation controls:

• indicatorPosition: Position of the indicators (inside, outside, none).
• indicatorHasIndex: Whether to display numerical indexes within the indicators.
• trigger: How indicators are triggered (hover, click).
• arrow: Display strategy for navigation arrows (hover, always, never).

<TuiCarousel 
  indicatorPosition="outside" 
  :indicatorHasIndex="false" 
  arrow="always"
  trigger="click"
>
  ...
</TuiCarousel>

API Reference

TuiCarousel Props

Property	Type	Default	Description
height	Number	-	Height of the carousel container (px).
initialIndex	Number	0	Initially active index.
appearance	String	'default'	Appearance mode: default or card.
direction	String	'h'	Carousel direction: h (horizontal) or v (vertical).
autoplay	Boolean	true	Whether to switch automatically.
interval	Number	3000	Time interval for automatic switching (ms).
loop	Boolean	true	Whether to loop playback.
pauseOnHover	Boolean	true	Whether to pause autoplay on mouse hover.
trigger	String	'hover'	Indicator trigger method: hover or click.
arrow	String	'hover'	Arrow display strategy: always, hover, or never.
indicatorPosition	String	'inside'	Position of indicators: inside, outside, or none.
indicatorHasIndex	Boolean	true	Whether to show numerical indexes in indicators.
cardScale	Number	0.8	Scaling ratio of inactive cards in card mode.
motionBlur	Boolean	true	Whether to enable motion blur during switching.
borderRadius	Number	-	Container border radius.
sequentialRolling	Boolean	true	Whether to enable sequential rolling logic.
resizeObserver	String	'global'	Size monitoring strategy: self, global, or none.

TuiCarousel Events

Event Name	Description	Callback Parameters
change	Triggered when the slide switches.	(currentIndex, prevIndex)

TuiCarousel Methods (Exposed)

Method Name	Description	Parameters
setActiveItem	Manually switch to a specific index.	(index: Number)
prev	Switch to the previous slide.	-
next	Switch to the next slide.	-

TuiCarouselItem Props

Property	Type	Default	Description
title	String	-	Title of the mask layer.
description	String	-	Description text for the mask layer.
hasLinkButton	Boolean	false	Whether to show a "Details/Link" button.

TuiCarouselItem Events

Event Name	Description	Callback Parameters
navigateTo	Triggered when the navigation button is clicked.	-