🎠
Carousel Pilot

A zero-dependency, framework-agnostic web component that enhances your existing scrollable content with carousel functionality. The Carousel is yours, but Carousel Pilot handles navigation (prev/next), active state, autoplay, infinite loop and scroll tracking.

Why?

Carousels are hard. You either use a heavy JS-based library or you gotta build things on your own. CSS scroll snapping has made it easier to build lightweight carousels, but some functionality like having the slides loop around are still heavily dependent on JS, and notably a pain to implement.

With Carousel Pilot you can have the both of best worlds: the scrolling and snapping is still handled by your CSS, responsive and reliable, but, if JavaScript is available, you can have Carousel Pilot jump in and add the extra goodies it provides, including a smooth infinite loop experience.

The cost? 17.7kB (gzipped). It's not the most lightweight option out there, but hopefully it's the most straightforward one to use.

How it works

Carousel Pilot is a custom element (<carousel-pilot>) that wraps your existing scrollable track. It doesn't impose any layout or styles — you style the track and slides however you want (flexbox, CSS scroll snap, etc.) and Carousel Pilot wires up the behavior.

It is built with Svelte 5, but works with any framework or no framework at all.

Installation

With NPM

npm install carousel-pilot

With a bundler (Vite, Webpack, Rollup, etc.)

Import once anywhere in your app — this registers the custom element globally:

import 'carousel-pilot';

In a Svelte project

import 'carousel-pilot';
// or, to use the Svelte component directly:
import { CarouselPilot } from 'carousel-pilot';

Via CDN / plain HTML

<script type="module" src="https://unpkg.com/carousel-pilot/dist/carousel-pilot.js"></script>

Usage Docs

Basic example

The only required piece is a scrollable track element marked with data-carousel-track. Everything else is optional.

<carousel-pilot>
  <ul data-carousel-track>
    <li>Slide 1</li>
    <li>Slide 2</li>
    <li>Slide 3</li>
  </ul>

  <!-- Optional navigation -->
  <button data-carousel-prev>Prev</button>
  <span>Slide <span data-carousel-currentIndex>1</span> of 3</span>
  <button data-carousel-next>Next</button>
</carousel-pilot>

You are responsible for the track's CSS layout. A typical setup with CSS scroll snap:

[data-carousel-track] {
  display: flex;
  gap: 1rem;
  overflow: auto;
  scroll-snap-type: x mandatory;
}

[data-carousel-track] > li {
  flex: 0 0 300px;
  scroll-snap-align: start;
}

Slot conventions

Mark elements inside <carousel-pilot> with these data attributes to connect them:

Props

Selectors

These props accept a CSS selector string. Each one falls back to its corresponding data-* attribute if left empty.

Behavior

CSS injection

Autoplay

Loop

JavaScript API

const carousel = document.querySelector('carousel-pilot');

carousel.scrollToIndex(2);       // scroll to a specific slide (0-based)
carousel.scrollNext();           // scroll forward one slide
carousel.scrollPrev();           // scroll backward one slide

Events

carousel.addEventListener('slide-change', (e) => {
  console.log(e.detail.index); // 0-based index of the new active slide
  console.log(e.detail.total); // total number of slides
});

carousel.addEventListener('autoplay-started', () => { /* ... */ });
carousel.addEventListener('autoplay-stopped', (e) => {
  console.log(e.detail.paused); // true = paused (hovering), false = stopped permanently
});