Carousel

Features

Setup

How It Works

I started coding a carousel library on top of SwiperJS for days until I remembered how difficult it always is to work with – especially when it came to controlling the styling. So I threw that library in the trash.

This new library was made to be easy to work with (especially on Webflow) without fighting unexpected Javascript shenanigans. You style things like always and control item sizes and spacing with standard CSS properties.

In the background, ResizeObserverCopy detects changes and automatically recalculates positions and boundaries. CSS Scroll Snap handles alignment. scrollIntoView()Copy provides the smooth programmatic navigation.

The benefit of leveraging native browser features instead of a library like SwiperJS is that the carousel gets GPU acceleration and performance optimizations for free. And it's just smoother. Less JavaScript, better performance, smoother scrolling.

Structure

There's three elements required:

• [data-carousel="container"]Copy – the outermost container, used for scoping a specific instance.
• [data-carousel="track"]Copy – the horizontal list that houses all the items.
• [data-carousel="item"]Copy – the individual slides.

The purpose of the [data-carousel="container"]Copy element is three-fold:

• It allows for automatic unique instance detection. Translation: you can simply have elements like the previous/next navigation buttons exist within the [data-carousel="container"]Copy , and the code already knows those buttons are for that specific carousel. It won't randomly start moving another carousel on another part of the page.
• It works perfectly with Webflow CMS. How do you get navigation buttons inside Webflow's Collection List if you can't put non-CMS things inside a Collection List? Exactly. Now you can.
• Flexibility for future features. Wink.

Webflow CMS

To match up with the Webflow Collection List structure:

1. [data-carousel="container"]Copy – goes on the Collection List WrapperCopy (if you don't care for navigation buttons), or anywhere as an ancestor of the Collection List WrapperCopy.
2. [data-carousel="track"]Copy – goes on the Collection ListCopy
3. Copy – goes on the (you guessed it!)

<div data-carousel="container">
  <div data-carousel="track">
    <div data-carousel="item">Item 1</div>
    <div data-carousel="item">Item 2

Customization

Core Attributes

Configure the carousel with data attributes on the container element:

Navigation Elements

Optional navigation controls that work automatically when placed inside the container:

Keyboard Navigation

When enabled, Arrow LeftCopy and Arrow RightCopy navigate between items. For those with huge keyboards, HomeCopy jumps to first item and EndCopy jumps to the last item.

To enable keyboard navigation:

<div data-carousel="container" data-carousel-keyboard="true">
  <!-- Rest of the track/items -->
</div>

Spacing and Positioning

Use CSS gapCopy on the [data-carousel="track"]Copy to control spacing.

The library also works with CSS scroll-paddingCopy (container insets) and scroll-marginCopy (per-item offsets) for controlling snap positioning. For the variants on this page, all of them have scroll-paddingCopy on the track element.

State Classes

The library applies state classes that you can style however you want.

Here's an example from the prev/next buttons on all the variants on this page:

/* Arrow initial styles */
.carousel_arrow {
  cursor: pointer;
  transition:
    opacity 200ms ease-in-out,
    color 150ms ease-in-out;
}
 
/* For a disabled arrow */

JavaScript API

Manual Initialization

// Auto-initializes on page load by default
// Or manually initialize:
const carousel = new Carousel(
  document.querySelector('[data-carousel="container"]'),
);
 
// Or using selector:
const carousel =

Instance Methods

carousel.next(); // Go to next item
carousel.prev(); // Go to previous item
carousel.goTo(2); // Go to specific index (0-based)
carousel.getActiveIndex

All methods are chainable:

carousel.next().next().refresh();

Events

carousel.on("change", (e) => {
  console.log(`Active item: ${e.index}`);
})

Or use native DOM events:

container.addEventListener("carousel:change", (e) => {
  console.log(e.detail); // { carousel, index }
});

Available events:

Global Registry

Access all carousel instances:

// Get all instances
const instances = window.CarouselInstances;
 
// Get specific instance by ID
const carousel = instances.get("carousel-1");
 
// Iterate over all
instances.forEach

Dynamic Content

When adding/removing items, call refresh()Copy:

const track = carousel.track;
const newItem = document.createElement("div");
newItem.setAttribute("data-carousel", "item");
newItem.

For major structural changes, destroy and reinitialize:

carousel.destroy();
const newCarousel = new Carousel(container);

FAQ