@oom/carousel

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

Install

Requirements:

• NPM or Yarn to install the package
• It's recommended to use the Scroll Behaviour polyfill to have better support for more browsers
• For browsers not supporting custom elements, you can use this polyfill

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

Usage

HTML

Let's start with the following html code:

<my-carousel role="region" aria-label="Gallery" tabindex="0">
    <div><img src="http://placehold.it/500x300"></div>
    <div><img src="http://placehold.it/500x300"></div>
    <div><img src="http://placehold.it/500x300"></div>
    <div><img src="http://placehold.it/500x300"></div>
    <div><img src="http://placehold.it/500x300"></div>
    <div><img src="http://placehold.it/500x300"></div>
    <div><img src="http://placehold.it/500x300"></div>
    <div><img src="http://placehold.it/500x300"></div>
    <div><img src="http://placehold.it/500x300"></div>
    <div><img src="http://placehold.it/500x300"></div>
</my-carousel>

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

CSS

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

JS

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

//Navigate
document.querySelector(".carousel-next").addEventListener(
  "click",
  (event) => carousel.index += 1,
);
document.querySelector(".carousel-prev").addEventListener(
  "click",
  (event) => carousel.index -= 1,
);

Player

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
player.play();

//Start the slideshow with 10 seconds to wait between slides
player.play(10000);

//Stop
player.stop();

API

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
carousel.next(); //Move the scroll to next
carousel.prev(); //Move the scroll to previous

Demo and tests

• Demo: https://oom-components.github.io/carousel/demo
• Tests: https://oom-components.github.io/carousel/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