Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Carousel with the following features:

  • No dependencies
  • Light: Less than 200 lines of code (including comments and spaces)
  • Follows the progressive enhancement strategy:
    • Works with just html
    • Works better with html and css
    • Works much better with html, css and js
    • Works much much better when js polyfills are not needed
  • High performance: Use native scroll to move the elements.
  • No need to wait for javascript to build the carousel.
  • No styles or themes are provided with this package. You decide how the carousel must look.
  • Support for touch devices
  • Support for keyboard
  • Build with modern javascript, using ES6 modules and custom elements



npm install @oom/carousel
npm install smoothscroll-polyfill
npm install @webcomponents/custom-elements



Let's start with the following html code:

<my-carousel role="region" aria-label="Gallery" tabindex="0">
    <div><img src=""></div>
    <div><img src=""></div>
    <div><img src=""></div>
    <div><img src=""></div>
    <div><img src=""></div>
    <div><img src=""></div>
    <div><img src=""></div>
    <div><img src=""></div>
    <div><img src=""></div>
    <div><img src=""></div>

<button class="carousel-next">Previous</button>
<button class="carousel-prev">Next</button>


Use css to define the carousel appearance:

my-carousel {
    overflow-x: scroll;
    display: flex;
    scroll-snap-type: x mandatory;
    -webkit-overflow-scrolling: touch;
my-carousel > div {
    flex: 0 0 auto;
    scroll-snap-align: center;


And finally use javascript for a complete experience:

import Carousel from "./carousel/carousel.js";

//Register the custom element
customElements.define("my-carousel", Carousel);

//Select the carousel
const carousel = document.querySelector("my-carousel");

  (event) => carousel.index += 1,
  (event) => carousel.index -= 1,


Use the module player to create a player and init a slideshow. Example:

import Player from "./carousel/player.js";

const player = new Player(carousel);

//Start the slideshow;

//Start the slideshow with 10 seconds to wait between slides;



This is a custom element that extends HtmlElement, so it innerit the same api of a standard html element with the following additions:

//Get/set the slide index
carousel.index = 3; //move to the slide 3
const currIndex = carousel.index; //get the current slide index
carousel.index += 1; //move to the next slide
carousel.index -= 1; //move to the previous slide

//Move the slide using scroll

let atBeginning = carousel.scrollFromLeft === 0; //Determine whether the scroll is at begining
let atTheEnd = carousel.scrollFromRight === 0; //Determine whether the scroll is at the end

carousel.scrollFromLeft = 0; //Performs a scroll to the beginning
carousel.scrollFromRight = 0; //Performs a scroll to the end; //Move the scroll to next
carousel.prev(); //Move the scroll to previous

Demo and tests

To run the demo locally, just clone this repository, enter in the directory and execute:

npm install
npm start

You should see something in the following urls:

  • Demo: http://localhost:8080/demo
  • Test: http://localhost:8080/tests