simple-carousel

A lightweight, dependency-free JavaScript carousel module with autoplay, navigation arrows, and dot indicators.

Ideal for projects needing a plug-and-play carousel component with no framework or build tools required.

Installation

Install from npm:

npm install simple-carousel

Usage

HTML Structure (required)

<div class="carousel">
  <div class="carousel-frame">
    <div class="carousel-track">
      <img src="1.jpg" class="carousel-image" />
      <img src="2.jpg" class="carousel-image" />
      <img src="3.jpg" class="carousel-image" />
    </div>
  </div>
  <button class="back-arrow">←</button>
  <button class="forward-arrow">→</button>
  <div class="navigation"></div>
</div>

JavaScript

import { initCarousel } from 'simple-carousel';

const container = document.querySelector('.carousel');
const { cleanup } = initCarousel(container);

// Optional: call cleanup() if the carousel is removed from the DOM
// cleanup();

Expected HTML Classes

Your markup should include the following class names for proper behavior:

| Class Name | Description | |--------------------|--------------------------------------------------| | .carousel | Main carousel container (pass this to the module)| | .carousel-frame | The visible window for images | | .carousel-track | The inner track that slides left/right | | .carousel-image | Each image in the carousel | | .back-arrow | Button to navigate to the previous image | | .forward-arrow | Button to navigate to the next image | | .navigation | Container for the auto-generated dots |

Features

• Auto-play with pause on hover
• Navigation arrows
• Dot indicators
• Resizes dynamically
• Keyboard-friendly dot navigation
• No dependencies
• cleanup() support for single-page apps

API

initCarousel(container: HTMLElement): { cleanup: () => void }

• container: The root DOM element containing the carousel
• Returns: An object with a cleanup() function that removes all event listeners and intervals created by the module

Customization

You can style the carousel freely using CSS. Here’s an example to get started:

.carousel {
  position: relative;
  overflow: hidden;
}

.carousel-frame {
  width: 100%;
}

.carousel-track {
  display: flex;
  transition: transform 0.4s ease;
}

.carousel-image {
  min-width: 100%;
  object-fit: cover;
}

.navigation {
  display: flex;
  justify-content: center;
  margin-top: 10px;
}

.dot {
  width: 10px;
  height: 10px;
  margin: 0 5px;
  border-radius: 50%;
  background: #ccc;
  cursor: pointer;
}

.active-dot {
  background: #333;
}

Example

const carousel = document.querySelector('.carousel');
const { cleanup } = initCarousel(carousel);

// Later if needed
// cleanup();

License

MIT

Contributions

Contributions and issues are welcome! Open a pull request or submit an issue if you find a bug or want to suggest an improvement.