Timed continuous carousel that uses vanilla JavaScript & CSS animations.
npm install continuous-carousel

A lightweight, performant carousel library using vanilla JavaScript and CSS animations. Features automatic continuous scrolling with support for both horizontal and vertical directions.
- 🎯 Lightweight - ~8KB minified + gzipped
- âš¡ Performant - 60fps animations using requestAnimationFrame
- 📱 Responsive - Auto-adjusts on resize with ResizeObserver
- 🔋 Battery-friendly - Pauses when off-screen using IntersectionObserver
- ♿ Accessible - ARIA live regions for screen readers
- 🎨 Customizable - CSS custom properties for easy styling
- 📦 Zero dependencies - Pure vanilla JavaScript
- 🔧 Flexible API - Programmatic control with play/pause/destroy
``bash`
npm install continuous-carouselor
pnpm add continuous-carouselor
bun add continuous-carousel
CDN:
`html`
ES Module:
`javascript`
import ContinuousCarousel from 'continuous-carousel';
`html`
`html`
`javascript
// Simple usage
const carousel = ContinuousCarousel('myCarousel');
// With options
const carousel = ContinuousCarousel('myCarousel', {
interval: 3000,
pauseOnHover: true,
onSlideChange: (index) => {
console.log('Current slide:', index);
}
});
`
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| direction | string | 'horizontal' | Scroll direction: 'horizontal' or 'vertical' |numVisible
| | number | 1 | Number of items visible at once |interval
| | number | 2000 | Time between transitions (ms) |transitionDuration
| | number | 1000 | Transition animation length (ms) |reverse
| | boolean | false | Scroll in opposite direction (right-to-left or bottom-to-top) |pauseOnHover
| | boolean | false | Pause animation on mouse hover |pauseOnFocus
| | boolean | false | Pause animation when element focused |autoplay
| | boolean | true | Start animation automatically |observeVisibility
| | boolean | true | Pause when off-screen (IntersectionObserver) |observeResize
| | boolean | true | Recalculate on resize (ResizeObserver) |announceSlides
| | boolean | true | Announce slide changes for screen readers |onSlideChange
| | function | null | Callback fired on slide change: (index) => {} |onPause
| | function | null | Callback fired when paused |onPlay
| | function | null | Callback fired when played |onDestroy
| | function | null | Callback fired when destroyed |
The ContinuousCarousel() function returns an object with the following methods:
`javascript
const carousel = ContinuousCarousel('myCarousel');
// Control playback
carousel.play(); // Resume animation
carousel.pause(); // Pause animation
carousel.destroy(); // Stop and cleanup
// Update configuration
carousel.updateConfig({ interval: 5000 });
// Access properties
carousel.container; // HTML element
carousel.config; // Current configuration
`
`html
`
`html
`
`html
`
`javascriptSlide ${index} is now active
const carousel = ContinuousCarousel('myCarousel', {
interval: 4000,
transitionDuration: 800,
pauseOnHover: true,
onSlideChange: (index) => {
console.log();`
}
});
`javascript
// Scroll right instead of left
ContinuousCarousel('myCarousel', { reverse: true });
// Scroll down instead of up
ContinuousCarousel('myCarousel', {
direction: 'vertical',
reverse: true
});
`
Or via HTML attribute:
`html`
...
`html



`
The carousel uses CSS custom properties for easy customization:
`css
.c-carousel-container {
/ Override defaults /
--carousel-item-width: 300px;
--carousel-item-height: 200px;
--carousel-transition-duration: 1000ms;
}
/ Custom item styles /
.c-carousel-item {
background: #f0f0f0;
display: flex;
align-items: center;
justify-content: center;
}
`
Modern browsers with ES6 module support:
- Chrome/Edge 61+
- Firefox 60+
- Safari 11+
- Opera 48+
For older browsers, use the transpiled UMD build (continuous-carousel.min.js`).
Check out the live demos for more examples:
- Horizontal and vertical carousels
- Reverse scroll direction
- Advanced features and API usage
See MIGRATION.md for upgrade instructions from earlier versions.
Contributions are welcome! Please read the contribution guidelines first.
Continuous Carousel is released under the MIT license.