Skip to content

oom-components/carousel

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@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 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

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