Carousel

Carousel component for displaying images, cards, or any content. Equipped with premium built-in 3D visual effects rivaling top-tier carousel libraries like Splide Premium.

Standard Slide

Standard gallery scroll, featuring default slide transition.

Basic Usage

Performance Optimization

The component has been deeply optimized for smooth performance with large image sets.

Large Dataset (Lazy Rendering + GPU Acceleration)

Performance Features:

• Lazy Rendering: Only renders the currently visible items plus a small buffer, dramatically reducing DOM nodes
• GPU Acceleration: Uses translate3d + willChange to trigger GPU compositing layers
• RAF Animation: Uses requestAnimationFrame for smooth 60fps animations
• Shallow Reactivity: Uses shallowRef to reduce reactivity tracking overhead
• Map Indexing: O(1) complexity lookup, improving responsiveness with large datasets

Advanced Configuration & Custom Slots

Fully matches mature frameworks, supporting controls like `dot-type` (dot/line), `dot-placement`, `mousewheel` support, `space-between` gap, and allows overriding navigations through named slots.

Config and Slots Example

Interactive Configuration Playground

Use the controls below to change `dot-type`, `dot-placement`, `direction`, and `show-arrow` and see the carousel update in real time. This demo shows only the interactive preview, consistent with other component examples.

Diverse configuration

Seamless Fade

Set effect="fade" to enable seamless fade-in and fade-out transition.

Fade Transition

Splide Premium Array Showcase

Implements all top-tier visual arrays without WebGL(Three.js) weight by employing a highly optimized pure CSS 3D translation engine.

1. Depth Stacking (Card)

Use effect="card" to render a dimensional depth where inactive cards automatically stack backwards.

Card Mode

2. Classic iTunes (Coverflow)

Set effect="coverflow". The gallery edges angle inward in a stunning 3D Coverflow presentation.

Coverflow

3. Center Zoom (Zoom)

Set effect="zoom" to emphasize center scale without perspective tilting.

Zoom Mode

4. Floating Perspective (Perspective)

Set effect="perspective" to produce a spatial step-down gallery layout.

Perspective Scroll

Advanced Mask Effects

Incredible dynamic masks utilizing highly optimized CSS algorithms rather than bulky WebGL libraries, ensuring performance is smooth 60fps across all devices.

1. Dissolve (Smoke Filter)

Use effect="dissolve" to trigger an immersive smoke-like dissolve and contrast filter.

Dissolve

2. Fiber Mask

Set effect="fiber" for a diagonal venetian blind wipe pattern perfectly simulating the fiber transitions.

Fiber Mask

3. Wave Mask

Set effect="wave". Wraps the incoming view in an animated bezier curve utilizing dynamic SVG encoding.

Wave Mask

4. Radial Gradient Mask

Set effect="radial" to zoom revealing contents from a centered focal hole.

Radial Mask

5. Cloud Mask

Set effect="cloud" for a high magnitude cloud shaped mask wipe.

Cloud Mask

3D rotation and spatial effects

Seven additional 3D rotation, depth, and pop-out effects for an immersive carousel experience.

Cube

Set effect="cube" for a cube-style 3D rotation between slides.

Flip

Set effect="flip" for a horizontal page-flip effect.

Cylinder

Set effect="cylinder" to arrange slides along a cylinder for a strong 3D wrap.

Stack

Set effect="stack" so the current slide is in front and others stack behind.

Parallax

Set effect="parallax" for parallax-style depth between slides.

Popout

Set effect="popout" so the active slide pops forward with perspective on neighbors.

Rotate3D

Set effect="rotate3d" for full XYZ rotation and maximum 3D depth.

Effect / Cards (Swiper-style)

Set effect="cards" for a Swiper effect-cards-style layout: the center slide stays prominent while neighboring slides remain visible with layered 3D stacking.

3D fold / stereoscopic focus

Set effect="fold" for a 3D fold stereoscopic focus-style effect with strong perspective and page-fold transitions.

Use in Nuxt

YhCarousel and YhCarouselItem work in Nuxt 3/4 after registering @yh-ui/nuxt. The initial slide structure can be rendered on the server, and interactive effects continue after hydration.

Use in Nuxt

SSR notes: Props, slots, and events stay aligned across SSR and hydration. If you want a static first paint for SEO-sensitive pages, disable autoplay for the initial render.

API

Props

Name	Description	Type	Default
current-index	Current index (controlled)	number	0
default-index	Default index (initial value for uncontrolled)	number	0
autoplay	Enable autoplay	boolean	false
interval	Autoplay interval (ms)	number	3000
loop	Enable loop playback	boolean	true
effect	Transition effect	'slide' | 'fade' | 'card' | 'coverflow' | 'zoom' | 'perspective' | 'dissolve' | 'fiber' | 'wave' | 'radial' | 'cloud' | 'cube' | 'flip' | 'cylinder' | 'stack' | 'parallax' | 'popout' | 'rotate3d' | 'cards' | 'fold' | 'custom'	'slide'
direction	Carousel direction	'horizontal' | 'vertical'	'horizontal'
show-arrow	Arrow display timing	'always' | 'hover' | 'never'	'hover'
show-dots	Show indicator dots	boolean	true
dot-trigger	Indicator trigger method	'click' | 'hover'	'click'
dot-placement	Indicator position	'top' | 'bottom' | 'left' | 'right' | 'inner-top' | 'inner-bottom' | 'inner-left' | 'inner-right'	'bottom'
dot-type	Indicator style	'dot' | 'line'	'dot'
keyboard	Enable keyboard control (arrow keys)	boolean	false
pause-on-hover	Pause autoplay on hover	boolean	true
draggable	Enable drag navigation	boolean	false
mousewheel	Enable mousewheel navigation	boolean	false
space-between	Item gap (slide mode, px)	number	0
card-gutter	Gap between adjacent cards (card-like effects, px)	number	20
slides-pre-view	Number of items shown per view	number | 'auto'	1
duration	Transition duration (ms)	number	500
theme-overrides	Component-level theme variable overrides	ComponentThemeVars	undefined

Events

Event	Payload	Description
update:currentIndex	(index: number)	Emitted when the current slide index changes
change	(index: number, prevIndex: number)	Emitted when the active slide changes

Slots

Name	Parameters	Description
default	-	Carousel items; use with YhCarouselItem
arrow	{ total, currentIndex, to, prev, next }	Custom previous and next controls
dots	{ total, currentIndex, to }	Custom indicator content
prev-arrow	-	Custom previous arrow icon
next-arrow	-	Custom next arrow icon

Expose

Use the component ref to access the following instance members:

Name	Type	Description
to / jump	(index: number) => void	Scroll to specific slide index
prev	() => void	Previous slide
next	() => void	Next slide
getCurrentIndex	() => number	Get current slide index
currentIndex	number	Current active index

Theme Variables

Variable	Description	Default
--yh-carousel-dot-color	Dot default color	rgba(255, 255, 255, 0.4)
--yh-carousel-dot-active-color	Dot active color	#ffffff
--yh-carousel-dot-size	Dot size	8px
--yh-carousel-dot-active-width	Active line-dot width	24px
--yh-carousel-arrow-bg	Arrow background	rgba(255, 255, 255, 0.2)
--yh-carousel-arrow-hover-bg	Arrow hover background	rgba(255, 255, 255, 0.35)
--yh-carousel-arrow-color	Arrow icon color	#ffffff
--yh-carousel-arrow-size	Arrow button size	36px
--yh-carousel-arrow-icon-size	Arrow icon size	20px
--yh-carousel-transition-timing	Transition timing function	cubic-bezier(0.4, 0, 0.2, 1)

Type Exports

Name	Description
YhCarouselProps	Props type for YhCarousel
YhCarouselEmits	Emits type for YhCarousel
YhCarouselSlots	Slots type for YhCarousel
YhCarouselExpose	Expose type for YhCarousel
YhCarouselEffect	Carousel effect union
YhCarouselDirection	Direction union
YhCarouselArrow	Arrow display strategy union
YhCarouselTrigger	Dot trigger union
YhCarouselDotPlacement	Dot placement union
YhCarouselItemProps	Props type for YhCarouselItem
YhCarouselItemSlots	Slots type for YhCarouselItem
YhCarouselInstance	Public instance type for YhCarousel
YhCarouselItemInstance	Public instance type for YhCarouselItem

Carousel Item Props

Name	Description	Type	Default
name	Name, for jumping by name	string	undefined