Skip to content

oom-components/carousel

master
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?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 

@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