Registry / web-framework / vue3-carousel

vue3-carousel

JSON →
library0.17.0jsnpmunverified

vue3-carousel is a modern, lightweight, and responsive carousel component designed specifically for Vue 3 applications. Its current stable version is 0.17.0, and it maintains an active release cadence, frequently adding new features, performance enhancements, and bug fixes, with minor versions released every few weeks. Key differentiators include built-in support for responsive breakpoints, infinite scroll with `wrapAround`, touch/mouse dragging, mouse wheel navigation, autoplay functionality, accessible keyboard navigation, and vertical sliding mode. It also provides dedicated components for navigation and pagination, and ships with TypeScript types for improved developer experience. The project is actively maintained with a focus on performance and accessibility.

web-framework
npm install vue3-carousel
github ↗package ↗
INSTALL
IMPORT
SIG · VUE3-CAROUSEL
V
vue3-carousel
web-frameworkjavascriptv0.17.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Carousel
✓ import { Carousel } from 'vue3-carousel'
✗ const Carousel = require('vue3-carousel').Carousel
Main carousel component for rendering the slider.
Slide
✓ import { Slide } from 'vue3-carousel'
✗ import Slide from 'vue3-carousel/Slide'
Used as a slot for individual carousel items within the Carousel component.
Pagination
✓ import { Pagination } from 'vue3-carousel'
✗ import { carouselPagination } from 'vue3-carousel'
A component to display pagination dots. Typically used in the '#addons' slot.
Navigation
✓ import { Navigation } from 'vue3-carousel'
✗ import { CarouselNav } from 'vue3-carousel'
A component to display navigation arrows. Typically used in the '#addons' slot.
CSS Styles
✓ import 'vue3-carousel/carousel.css'
✗ import 'vue3-carousel/dist/carousel.css'
Essential CSS styles for the carousel to function correctly. Must be imported once globally or per component.

Demonstrates basic usage of the Carousel component with slides, navigation, and pagination, including responsive and autoplay features.

<script setup> import 'vue3-carousel/carousel.css' import { Carousel, Slide, Pagination, Navigation } from 'vue3-carousel' const carouselConfig = { itemsToShow: 2.5, wrapAround: true, autoplay: 3000, mouseDrag: true, transition: 500 } </script> <template> <h2 style="text-align: center; margin-bottom: 20px;">My Awesome Carousel</h2> <Carousel v-bind="carouselConfig"> <Slide v-for="slide in 10" :key="slide"> <div class="carousel__item" style="background-color: #f0f0f0; padding: 40px; border-radius: 8px; font-size: 2em;"> {{ slide }} </div> </Slide> <template #addons> <Navigation /> <Pagination /> </template> </Carousel> </template>
Debug
Known issues
breakingThe peer dependency for Vue has been updated to require version `^3.5.0` since v0.11.0. Older Vue 3 versions might lead to compatibility issues or unexpected behavior.
fix
Ensure your project uses Vue 3.5.0 or newer: `npm update vue` or `yarn upgrade vue`.
affects: >=0.11.0
gotchaMissing the essential CSS import `import 'vue3-carousel/carousel.css'` will result in an unstyled and non-functional carousel. The component relies heavily on these styles for layout and animations.
fix
Add `import 'vue3-carousel/carousel.css'` to your main entry file (e.g., `main.js`/`main.ts`) or within the script setup block of components using the carousel.
affects: >=0.1.0
gotchaIn versions prior to 0.17.0, there were critical issues with mobile scrolling behavior, auto mode crashing, and `wrapAround` with `itemsToScroll` not working as expected. These could lead to poor user experience on mobile devices.
fix
Upgrade to `vue3-carousel` v0.17.0 or newer to benefit from fixes for mobile scrolling, auto mode, and `wrapAround` functionality: `npm update vue3-carousel`.
affects: <0.17.0
breakingRefactors in v0.15.0 using composable functions might slightly alter internal component structure, though the public API generally remains stable. Direct manipulation of internal instances via `ref` might require adjustments.
fix
Review the official documentation for any breaking changes related to advanced usage or custom implementations that rely on internal component structure. Most basic usage remains unaffected.
affects: >=0.15.0
gotchaConfiguring `itemsToShow` with decimal values (e.g., 2.5) requires careful consideration, especially for responsive breakpoints. Incorrect configuration can lead to uneven slide display or layout issues.
fix
Always test `itemsToShow` configurations across various screen sizes and define appropriate `breakpoints` if aiming for fractional slide visibility.
affects: >=0.1.0
gotchaSSR (Server-Side Rendering) hydration issues were reported and fixed in v0.10.0. If you are using Nuxt or other SSR frameworks with older versions, you might encounter hydration mismatches.
fix
Upgrade to v0.10.0 or later to resolve known SSR hydration problems. For Nuxt users, consider using the `vue3-carousel-nuxt` module for better integration.
affects: <0.10.0
Errors
Common errors & fixes
Failed to resolve component: carousel
The `Carousel` component was not properly imported or registered with Vue.
fix
Ensure you have `import { Carousel } from 'vue3-carousel'` in your script block and that the component is used correctly in your template (e.g., `<Carousel>`).
Uncaught TypeError: Cannot read properties of undefined (reading 'width') at setup
This often occurs when the carousel's CSS is not loaded, leading to elements having no defined dimensions, or when mounted in an environment without a valid DOM context (e.g., during SSR without proper hydration setup).
fix
Verify `import 'vue3-carousel/carousel.css'` is present and correctly applied. If in an SSR environment, ensure you're using a compatible version and consider client-only rendering if issues persist, or use the Nuxt module.
Prop 'itemsToShow' validation failed: value must be a number greater than 0.
The `itemsToShow` prop received an invalid value (e.g., null, undefined, 0, or a non-numeric string).
fix
Provide a valid positive number for `itemsToShow`, ensuring it's bound correctly if it comes from dynamic data.
Vue warn]: Non-function value encountered for slot "addons". The slot content for "addons" must be a function.
You are trying to pass raw components directly to the `#addons` slot, but Vue 3 expects a function returning the VNodes for named slots.
fix
Wrap your addon components within a `<template #addons>...</template>` block, as shown in the quickstart example, ensuring it's treated as a slot content function.
Upgrade
Version history
0.17.0latest on npm
Audit
Dependencies
vuerequiredPeer dependency for Vue 3 application integration. Requires Vue 3.5.0 or higher.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
githubhttps://github.com/ismail9k/vue3-carousel ↗
packagehttps://www.npmjs.com/package/vue3-carousel ↗
vue3-carousel — npm install vue3-carousel · libregistry