https://github.com/jonchretien/continuous-carousel
A timed continuous carousel that uses vanilla JavaScript & CSS animations.
https://github.com/jonchretien/continuous-carousel
carousel css css-animations javascript vanilla-javascript
Last synced: 5 months ago
JSON representation
A timed continuous carousel that uses vanilla JavaScript & CSS animations.
- Host: GitHub
- URL: https://github.com/jonchretien/continuous-carousel
- Owner: jonchretien
- License: mit
- Created: 2015-03-11T23:23:43.000Z (over 11 years ago)
- Default Branch: main
- Last Pushed: 2025-11-18T20:41:25.000Z (8 months ago)
- Last Synced: 2026-01-13T19:59:16.921Z (6 months ago)
- Topics: carousel, css, css-animations, javascript, vanilla-javascript
- Language: JavaScript
- Homepage:
- Size: 1.08 MB
- Stars: 22
- Watchers: 2
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Continuous Carousel ðŸŽ
[](https://www.npmjs.com/package/continuous-carousel)
[](https://opensource.org/licenses/MIT)
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](https://jonchretien.github.io/continuous-carousel/)**
## 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
**npm:**
```bash
npm install continuous-carousel
```
**CDN:**
```html
```
**ES Module:**
```javascript
import ContinuousCarousel from 'continuous-carousel';
```
## Quick Start
### 1. Add HTML markup
```html
- Slide 1
- Slide 2
- Slide 3
- Slide 4
```
### 2. Include CSS
```html
```
### 3. Initialize carousel
```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) |
| `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
### Horizontal Carousel (Single Item)
```html
- 1
- 2
- 3
ContinuousCarousel('carousel1');
```
### Horizontal Carousel (Multiple Items)
```html
- 1
- 2
- 3
- 4
- 5
- 6
ContinuousCarousel('carousel2');
```
### Vertical Carousel
```html
- A
- B
- C
ContinuousCarousel('carousel3');
```
### With Custom Options
```javascript
const carousel = ContinuousCarousel('myCarousel', {
interval: 4000,
transitionDuration: 800,
pauseOnHover: true,
onSlideChange: (index) => {
console.log(`Slide ${index} is now active`);
}
});
```
### Image Gallery
```html
-
-
-
ContinuousCarousel('gallery', {
interval: 5000,
pauseOnHover: true
});
```
## 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](https://jonchretien.github.io/continuous-carousel/) for more examples:
- Basic horizontal and vertical carousels
- Image galleries with captions
- Card showcases and testimonials
- News tickers and text scrollers
- Advanced features and API usage
## Migration from v0.2.x
See [MIGRATION.md](./MIGRATION.md) for upgrade instructions from v0.2.x to v0.3.0.
## Contributing
Contributions are welcome! Please read the [contribution guidelines](./CONTRIBUTING.md) first.
## License
Continuous Carousel is released under the [MIT license](https://github.com/jonchretien/continuous-carousel/blob/master/LICENSE.txt).