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. So I threw that library away. This new one was made to be super easy to work with (particularly on Webflow). You style elements, control item sizing, and manage spacing like you're always used to. No unexpected Javascript shenanigans.

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

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.

Webflow CMS

To match up with the Webflow Collection List structure:

1. [data-carousel-container]Copy – either 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</div

Customization

Core Attributes

Configure the carousel with data attributes on the container element:

Loop

Enable infinite-style navigation so the carousel wraps around when reaching either end. When loop is active, the previous/next buttons are never disabled.

<div data-carousel-container data-carousel-loop>
  <!-- ... -->
</div>

Loop applies to all forms of navigation: buttons, keyboard, scroll markers, autoplay, and the JavaScript API.

Scroll-by

By default, the carousel advances one item at a time. Set data-carousel-scroll-by="page"Copy to advance by the number of items currently visible in the viewport. This is useful for multi-item carousels where you want to scroll a full "page" of content at once.

<div data-carousel-container data-carousel-scroll-by="page">
  <!-- ... -->
</div>

The page calculation uses the actual container width, so it works correctly with variable-width items and across breakpoints.

Navigation Elements

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

You can place multiple instances of any navigation button or counter element within the same container. All of them will receive click listeners, disabled states, and content updates. This is useful for placing prev/next buttons in multiple locations (e.g., above and below the track).

Scroll Markers

Add scroll markers anywhere inside the carousel container. The library finds all [data-carousel-marker]Copy elements and clones the first one to match the number of navigable positions.

<div data-carousel-container>
  <div data-carousel="track">
    <div data-carousel="item">...</div>
    <div data-carousel="item">...</div

For custom counter displays like "2 of 5":

<div class="my-marker-styles">
  <button data-carousel-marker></button>
</div>
<div>
  <span data-carousel-counter-current></span>
  of
  <span data-carousel-counter-total></

The library automatically adds aria-label="Scroll to item X of Y"Copy and aria-selected="true"Copy on the active marker for accessibility.

Scroll markers use roving tabindex for keyboard navigation. Only the active marker is in the tab order — pressing Tab skips past inactive markers. When a marker has focus, Arrow LeftCopy / Arrow RightCopy move between markers (wrapping when data-carousel-loopCopy is enabled), and HomeCopy / EndCopy jump to the first and last marker.

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>
  <!-- Rest of the track/items -->
</div>

Autoplay

Automatically advance items on a timer. Combine with data-carousel-loopCopy for continuous cycling. Without loop, autoplay advances through all items, completes the progress animation on the last item, then stops cleanly — the container will have both .carousel-at-endCopy (position) and not .carousel-playingCopy (stopped).

<div data-carousel-container data-carousel-loop data-carousel-autoplay>
  <!-- ... -->
</div>

Autoplay Attributes

Autoplay with Custom Duration

<div
  data-carousel-container
  data-carousel-loop
  data-carousel-autoplay
  data-carousel-autoplay-duration="3000"
>
  <!-- Advances every 3 seconds -->
</div>

Play/Pause Button

Add a toggle button inside the container to let users control autoplay. The library toggles aria-labelCopy between "Stop autoplay" and "Start autoplay" automatically.

<div data-carousel-container data-carousel-loop data-carousel-autoplay>
  <div data-carousel="track">
    <div data-carousel="item">...</div>
    <div data-carousel="item">...

Restart Button

Add a restart button to let users go back to the first item and start autoplay again. Useful for non-loop carousels where autoplay has completed.

<div data-carousel-container data-carousel-autoplay>
  <div data-carousel="track">
    <div data-carousel="item">...</div>
    <div data-carousel="item">...</

Clicking the restart button navigates to the first item and starts autoplay fresh. Since navigating to the first item updates position classes, .carousel-at-endCopy is removed and .carousel-at-startCopy is added.

Pause Behavior

Autoplay uses a stop-on-action model. Any intentional user interaction fully stops autoplay. Only the play button (or calling play()Copy) restarts it.

Actions that stop autoplay:

• Navigation buttons (prev/next): Clicking prev/next stops autoplay.
• Marker clicks: Clicking a marker stops autoplay.
• Keyboard navigation: Arrow keys, Home, and End stop autoplay.
• Dragging/swiping: Manually scrolling the track to a different item stops autoplay.
• JavaScript API: Calling next()Copy, prev()Copy, goTo()Copy, or stop()Copy stops autoplay.

Temporary pauses (autoplay resumes automatically):

• Hover: Mouse enters the track (resumes on mouse leave). Opt-in via data-carousel-autoplay-pause-hover="true"Copy. Only the track area triggers this — hovering nav buttons or markers outside the track does not pause.
• Focus: A focusable element inside the track receives focus (resumes when focus leaves the track). Configurable via data-carousel-autoplay-pause-focusCopy. Focus moving to a nav button outside the track will resume autoplay.
• Viewport: The carousel scrolls out of view (resumes when at least 50% is visible again). Uses IntersectionObserverCopy.

Reduced Motion

When the user's operating system has prefers-reduced-motion: reduceCopy enabled, autoplay will not start. The container receives the carousel-reduced-motionCopy class. Calling play()Copy via JavaScript is also blocked.

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.

CSS Custom Properties

The library exposes state as CSS custom properties on the container element. Use these for dynamic styling without JavaScript.

Example: a progress bar that fills as you scroll through the carousel.

.carousel-progress-bar {
  width: calc(var(--carousel-progress) * 100%);
  height: 2px;
  background: currentColor;
  transition: width 150ms ease-out

Example: an autoplay progress indicator on each marker. Since --carousel-autoplay-progressCopy is set on the active marker (and reset to 0Copy on inactive markers), you can use it directly to build a per-item timer.

.carousel-marker-progress {
  transform: scaleX(var(--carousel-autoplay-progress, 0));
  transform-origin: left;
  transition: none;
}

State Classes

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

Example: style the play/pause button based on autoplay state.

/* Show pause icon while playing, play icon when stopped */
.carousel-playing [data-carousel-play-pause] .play-icon {
  display: none;
}
.carousel-playing [data-carousel-play-pause] .pause-icon {
  display: block;
}

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 = Carousel

Instance Methods

carousel.next(); // Go to next item (stops autoplay)
carousel.prev(); // Go to previous item (stops autoplay)
carousel.goTo(2); // Go to specific index (stops autoplay)
carousel

All methods are chainable (except getActiveIndexCopy and destroyCopy):

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

play()Copy

Starts autoplay fresh with a full duration timer. Has no effect when prefers-reduced-motion: reduceCopy is active. Requires data-carousel-autoplayCopy on the container — logs a warning if called without it.

stop()Copy

Stops autoplay completely. The carousel-playingCopy class is removed and progress resets to 0. Only play()Copy or clicking the play/pause button will restart it.

goTo(index)Copy

Navigates to the given 0-based index. If the index is beyond the last navigable position (in multi-item carousels where the last few items share a scroll position), it is silently clamped. If autoplay is running, it is stopped.

Events

The carousel dispatches DOM CustomEvents on the container element. Listen for them with addEventListenerCopy:

const container = document.querySelector('[data-carousel-container]');
 
container.addEventListener('carousel:snapchange', (e

Available events:

Instance Access

Access a carousel instance through the DOM element:

const container = document.querySelector('[data-carousel-container]');
const carousel = container._carousel;
 
carousel.next().next().refresh()

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);

Accessibility

The library adds semantic ARIA attributes automatically. You don't need to add any of these yourself — they're listed here so you know what to expect in the DOM.

All role attributes respect existing values — if you set a roleCopy on the track or markers in your HTML, the library won't override it.