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
• 🔒 TypeScript - Written in TypeScript with full type declarations

Installation

npm install continuous-carousel
# or
pnpm add continuous-carousel
# or
bun add continuous-carousel

CDN:

<link rel="stylesheet" href="https://unpkg.com/continuous-carousel/dist/continuous-carousel.min.css">
<script src="https://unpkg.com/continuous-carousel/dist/continuous-carousel.min.js"></script>

ES Module:

import ContinuousCarousel from 'continuous-carousel';

TypeScript:

import ContinuousCarousel from 'continuous-carousel';
import type { ContinuousCarouselConfig, ContinuousCarouselInstance } from 'continuous-carousel';

const carousel: ContinuousCarouselInstance = ContinuousCarousel('myCarousel', {
  interval: 3000,
  pauseOnHover: true,
});

Quick Start

1. Add HTML markup

<div id="myCarousel" class="c-carousel-container" data-direction="horizontal" data-num-visible="1">
  <ul class="c-carousel-group">
    <li class="c-carousel-item">Slide 1</li>
    <li class="c-carousel-item">Slide 2</li>
    <li class="c-carousel-item">Slide 3</li>
    <li class="c-carousel-item">Slide 4</li>
  </ul>
</div>

2. Include CSS

<link rel="stylesheet" href="dist/continuous-carousel.min.css">

3. Initialize carousel

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

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)

<div id="carousel1" class="c-carousel-container" data-direction="horizontal" data-num-visible="1">
  <ul class="c-carousel-group">
    <li class="c-carousel-item">1</li>
    <li class="c-carousel-item">2</li>
    <li class="c-carousel-item">3</li>
  </ul>
</div>

<script>
  ContinuousCarousel('carousel1');
</script>

Horizontal Carousel (Multiple Items)

<div id="carousel2" class="c-carousel-container" data-direction="horizontal" data-num-visible="3">
  <ul class="c-carousel-group">
    <li class="c-carousel-item">1</li>
    <li class="c-carousel-item">2</li>
    <li class="c-carousel-item">3</li>
    <li class="c-carousel-item">4</li>
    <li class="c-carousel-item">5</li>
    <li class="c-carousel-item">6</li>
  </ul>
</div>

<script>
  ContinuousCarousel('carousel2');
</script>

Vertical Carousel

<div id="carousel3" class="c-carousel-container" data-direction="vertical" data-num-visible="1">
  <ul class="c-carousel-group">
    <li class="c-carousel-item">A</li>
    <li class="c-carousel-item">B</li>
    <li class="c-carousel-item">C</li>
  </ul>
</div>

<script>
  ContinuousCarousel('carousel3');
</script>

With Custom Options

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

Reverse Scroll Direction

// Scroll right instead of left
ContinuousCarousel('myCarousel', { reverse: true });

// Scroll down instead of up
ContinuousCarousel('myCarousel', {
  direction: 'vertical',
  reverse: true
});

Or via HTML attribute:

<div id="myCarousel" class="c-carousel-container" data-direction="horizontal" data-num-visible="1" data-reverse="true">
  ...
</div>

Image Gallery

<div id="gallery" class="c-carousel-container" data-direction="horizontal" data-num-visible="1">
  <ul class="c-carousel-group">
    <li class="c-carousel-item">
      <img src="image1.jpg" alt="Image 1">
    </li>
    <li class="c-carousel-item">
      <img src="image2.jpg" alt="Image 2">
    </li>
    <li class="c-carousel-item">
      <img src="image3.jpg" alt="Image 3">
    </li>
  </ul>
</div>

<script>
  ContinuousCarousel('gallery', {
    interval: 5000,
    pauseOnHover: true
  });
</script>

Styling

The carousel uses CSS custom properties for easy customization:

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