Fast Carousel

A blazing-fast, lightweight, and customizable carousel library built for modern web performance.

FastCarousel relies on native CSS scroll-snap for layout and physics, resulting in zero layout thrashing, perfect Lighthouse scores, and a buttery-smooth experience on both mobile and desktop.

Features

• Performance First: Zero JavaScript layout calculations. Powered entirely by CSS scroll snapping.
• Responsive Breakpoints: Control slidesPerView and slidesToScroll at any screen size.
• Native Feel: Supports native mobile touch swiping and desktop mouse dragging.
• Custom Scrollbar: Includes a fully draggable, interactive custom scrollbar.
• Accessible (a11y): Automatically manages aria-hidden and focus states for off-screen slides.
• External Controls: Place your Next/Prev buttons anywhere on the page.
• Autoplay: Supports pausing on hover and automatically pauses when scrolled out of view to save CPU cycles.

Installation

Install the package via NPM:

  npm i fast-carousel

Getting Started

1. The HTML Structure

Add the following markup to your page. You can place the controls (next-btn, prev-btn) anywhere on your page, as long as you pass their selectors to the initialization script.

<div class="my-carousel" id="demo-carousel">
  <div class="carousel-track">
    <div class="carousel-slide">Slide 1</div>
    <div class="carousel-slide">Slide 2</div>
    <div class="carousel-slide">Slide 3</div>
    <div class="carousel-slide">Slide 4</div>
  </div>

  <div class="carousel-scrollbar">
    <div class="scrollbar-thumb"></div>
  </div>

  <div class="carousel-controls">
    <button class="prev-btn">Prev</button>
    <button class="next-btn">Next</button>
  </div>
</div>

2. Import the Styles

Import the base CSS file to handle the flex layouts and scroll-snapping physics.

Via JavaScript (Bundlers like Vite/Webpack):

import "fast-carousel/style.css";

Via HTML:

<link rel="stylesheet" href="node_modules/fast-carousel/dist/style.css" />

3. Initialize the Carousel

Import the class and initialize it by targeting your container ID.

import FastCarousel from "fast-carousel";

const myCarousel = new FastCarousel("#demo-carousel", {
  autoplay: false,
  autoplaySpeed: 3000,
  nextButton: ".next-btn", // Optional: CSS selector for your next button
  prevButton: ".prev-btn", // Optional: CSS selector for your prev button
  breakpoints: {
    // Mobile first
    0: {
      slidesPerView: 1,
      slidesToScroll: 1,
    },
    // Tablet
    768: {
      slidesPerView: 2,
      slidesToScroll: 2,
    },
    // Desktop
    1024: {
      slidesPerView: 4,
      slidesToScroll: 4,
    },
  },
});

Configuration Options

You can pass an options object as the second parameter when initializing the carousel.

| Option | Type | Default | Description | | ------------- | -------- | ---------------- | ------------------------------------------------------------------------------- | | autoplay | Boolean | false | Enables automatic scrolling. Pauses on hover or when out of view. | | autoplaySpeed | Number | 3000 | Time in milliseconds between auto-scrolls. | | nextButton | String | null | CSS selector for the "Next" button. Defaults to .next-btn inside the container. | | prevButton | String | null | CSS selector for the "Prev" button. Defaults to .prev-btn inside the container. | | breakpoints | Object | {...} | Define slidesPerView and slidesToScroll at different pixel widths. | | ariaLabel | String | 'Image Carousel' | The screen-reader label for the main carousel region. |

Customizing Styles

The library provides minimal styling to ensure layout and functionality. You are encouraged to style the slides and controls yourself!

The slide widths are calculated automatically via a CSS variable (var(--slide-width)). You can easily style your slides like this:

.carousel-slide {
  /* Required: Do not change the width calculation */
  width: var(--slide-width, 100%);

  /* Your custom styles */
  background: #3b82f6;
  border-radius: 8px;
  height: 300px;
}

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a new branch: git checkout -b feature/your-feature-name
3. Make your changes and commit: git commit -m "feat: add your feature"
4. Push to your fork: git push origin feature/your-feature-name
5. Open a Pull Request

Please make sure your code follows the existing JavaScript conventions and the project builds without errors before submitting.

License

This project is licensed under the MIT License.

Acknowledgements

Built with ❤️ by HapticHash. If you find this useful, consider leaving a ⭐ on the repo!