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.

View Live Demos

Features

- 🎯 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

Installation

``bash
npm install continuous-carousel


or

pnpm add continuous-carousel

or

bun add continuous-carousel
`

CDN:
`html


`

ES Module:
`javascript
import ContinuousCarousel from 'continuous-carousel';
`

Quick Start

$3

`html



`

$3

`html

`

$3

`javascript
// Simple usage
const carousel = ContinuousCarousel('myCarousel');

// With options
const carousel = ContinuousCarousel('myCarousel', {
interval: 3000,
pauseOnHover: true,
onSlideChange: (index) => {
console.log('Current slide:', index);
}
});
`

Configuration Options

| 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 |

API Methods

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
`

Examples

$3

`html



`

$3

`html



`

$3

`html



`

$3

`javascript
const carousel = ContinuousCarousel('myCarousel', {
interval: 4000,
transitionDuration: 800,
pauseOnHover: true,
onSlideChange: (index) => {
console.log(Slide ${index} is now active);
}
});
`

$3

`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



`

$3

`html



`

Styling

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;
}
`

Browser Support

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`).

Demos

Check out the live demos for more examples:

- Horizontal and vertical carousels
- Reverse scroll direction
- Advanced features and API usage

Migration

See MIGRATION.md for upgrade instructions from earlier versions.

Contributing

Contributions are welcome! Please read the contribution guidelines first.

License

Continuous Carousel is released under the MIT license.